diff --git a/.gitignore b/.gitignore index c7d750e..c4fd61b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ # editor-generated backup files *.bak +*~ diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst new file mode 100644 index 0000000..594723e --- /dev/null +++ b/docs/decisions/0001-namespacing-branches.rst @@ -0,0 +1,95 @@ +Namespacing Branches and Tags +############################# + +Status +****** + +Accepted + +Context +******* + +This ADR was written in response to this `Discourse thread`_. + +Currently, 2U continuous delivery tooling creates branches and tags +in the repository "global namespace." By that I mean that branches +and tags have the form ``release`` or ``release-candidate-3729``. +This is confusing because those branches and tags appear to be global, +officially sanctioned by the project, and authoritative. + +A result of this is that the official named releases of the platform +require a namespace specifier, for example, +``open-release/olive.master``. + +This is confusing to most members of the community and reflects the +prior stewardship arrangements for the project. + +It is not typical of open-source projects to allow participating +organizations to push organization specific branches and tags to the +canonical upstream. However, we recommend not prohibiting this at this +time. There are two reasons for that: + +1. This would require more substantial changes to participant deployment + systems that would delay getting value from this initial change. +2. The 2U branches and tags represent code that is battle-tested in + production at scale and are, thus, valuable sign posts for + community members. + +.. _Discourse thread: https://discuss.openedx.org/t/should-we-rename-the-release-branches/8827/7 + + +Decisions +********* + +1. We will *not* forbid project participants with write access to + repositories from pushing branches or tags to the canonical + upstream hosted at the openedx GitHub organization. +2. However, we *will* require that project participants namespace their + upstream branches and tags to clarify their origin and purpose. +3. The global namespace will be reserved for global project purposes. +4. Branches within *forks* of Open edX repositories may choose to follow this + guidance, but they do not need to. + +Going forward, branches and tags that originate from any specific +organization or user participating in the Open edX project must by namespaced +as follows: + +* ``$ORGANIZATION/$PURPOSE`` for organizations. +* ``$GITHUB_USER/$PURPOSE`` for contributors. + +For example: + +* ``acme/release`` +* ``acme/release-candidate-3729`` +* ``acme/our-feature`` +* ``e0d/my-feature`` + +In some cases, multiple namespaces may be appropriate. For example, ``e0d`` +may be working for ``acme`` on a project funded by ``wile-e-coyote``. When in +doubt, one should choose the namespace which best informs community who manages +the branch, which in this case would be either ``e0d`` or ``acme``. + +In the case of the global namespace, tags and branches may still be +further qualified to provide additional information and specificity. + +For example: + +* ``release`` would be considered in the global namespace. +* ``release/redwood`` would represent the branch for an officially- + sanctioned Open edX named release. + + +Consequences +************ + +#. Continuous delivery systems and other automation should be updated + across the ecosystem to use the proper naming convention for + branches and tags. Existing branches and tags should be updated to use the + new naming protocol. Axim will announce this to community members. +#. Axim will ensure that branch namespacing is communicated to new developers + via onboarding documentation. +#. Axim may prune newly-created branches and tags which don't use a proper + namespace. +#. Axim will announce its intent to remove batches of existing branches and + tags that don't use namespaces. Each batch will include a reasonable grace + period.