From ae7c93cef787343bedfb76b4f970780692dd5511 Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Wed, 7 Dec 2022 17:29:07 -0500 Subject: [PATCH 01/14] feat: first draft of namespacing proposal --- docs/decisions/0001-namespacing-branches.rst | 71 ++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/decisions/0001-namespacing-branches.rst diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst new file mode 100644 index 0000000..ff38d1d --- /dev/null +++ b/docs/decisions/0001-namespacing-branches.rst @@ -0,0 +1,71 @@ +Namespacing Branches and Tags +----------------------------- + +Status +====== + +Draft + +Context +======= + +This ADR was written in response to this `Discourse thread`_. + +Currently, 2U continuously delevery 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, +offically 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's not typical of open-source project to allow partipating +organizations to push branches and tags to the canonical upstream. +However, we recommend not pohibiting that at this time. There are two +reasons for that: + +1. This would require more substanial changes to partipant deployment + systems that would delay getting value from this 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. We will require that project partipants namespace their branches + and tags to clarify their origin and purpose +3. The global namespace will be reserved for global project purposes + +Going forward branches and tags that originate from any specific +organization partipatinging in the Open edX project must by namespaced +as follows: + +``acme/release`` + +or + +``acme/release-candidate-3729`` + + +Consquences +=========== + +1. Continuous delivery systems and other automation should be updated + across the ecosystem to use the proper naming convention for + branches and tags +2. Existing branches and tags should be updated to use the new naming + protocol +3. A reasonable grace period should be established to schedule and + complete the required work From 0db61a5699bf1a3b914b3f7a31f8ac9dc188e0ec Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Wed, 7 Dec 2022 17:35:01 -0500 Subject: [PATCH 02/14] fix: spelling/ignore --- .gitignore | 1 + docs/decisions/0001-namespacing-branches.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 07ac407..55e88ab 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ #ignore .idea directory .idea +*~ diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index ff38d1d..4a396c9 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -59,7 +59,7 @@ or ``acme/release-candidate-3729`` -Consquences +Consequences =========== 1. Continuous delivery systems and other automation should be updated From abd6c5c474d711c69a4d091d6ce428346fa8fc43 Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Thu, 8 Dec 2022 09:19:18 -0500 Subject: [PATCH 03/14] fix: spelling/grammar --- docs/decisions/0001-namespacing-branches.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index 4a396c9..a73ead9 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -11,27 +11,27 @@ Context This ADR was written in response to this `Discourse thread`_. -Currently, 2U continuously delevery tooling creates branches and tags +Currently, 2U continuous delevery 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, -offically sanctioned by the project, and authoritative. +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`` +``open-release/olive.master``. This is confusing to most members of the community and reflects the prior stewardship arrangements for the project. -It's not typical of open-source project to allow partipating -organizations to push branches and tags to the canonical upstream. -However, we recommend not pohibiting that at this time. There are two -reasons for that: +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 substanial changes to partipant deployment - systems that would delay getting value from this change. -2. The 2U branches and tags represent code that is battle tested in + 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. @@ -44,7 +44,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. We will require that project partipants namespace their branches +2. We will require that project participants namespace their branches and tags to clarify their origin and purpose 3. The global namespace will be reserved for global project purposes From 22d170cf41a4a73233f25781d686d064bfefa828 Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Thu, 8 Dec 2022 11:30:36 -0500 Subject: [PATCH 04/14] fix: Update docs/decisions/0001-namespacing-branches.rst Co-authored-by: Feanil Patel --- docs/decisions/0001-namespacing-branches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index a73ead9..e20177f 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -29,7 +29,7 @@ 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 substanial changes to partipant deployment +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 From 24069a2d9d5394390778a654838b5473dfa53048 Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Thu, 8 Dec 2022 13:12:06 -0500 Subject: [PATCH 05/14] fix: heading standard --- docs/decisions/0001-namespacing-branches.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index e20177f..dd75a04 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -1,13 +1,13 @@ Namespacing Branches and Tags ------------------------------ +############################# Status -====== +****** Draft Context -======= +******* This ADR was written in response to this `Discourse thread`_. @@ -39,7 +39,7 @@ time. There are two reasons for that: Decisions -========= +********* 1. We will not forbid project participants with write access to repositories from pushing branches or tags to the canonical @@ -60,7 +60,7 @@ or Consequences -=========== +************ 1. Continuous delivery systems and other automation should be updated across the ecosystem to use the proper naming convention for From 39e16eaf605d176c03f38674bb78d19d57948052 Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Thu, 8 Dec 2022 13:18:33 -0500 Subject: [PATCH 06/14] fix: responding the CR comments --- docs/decisions/0001-namespacing-branches.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index dd75a04..0f8befe 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -58,6 +58,12 @@ or ``acme/release-candidate-3729`` +In the case of the global namespace, tags and branches may still be further qualified to provide addition information and specificity. + +For example: + +``release/palm`` would represent the branch for an officially sanctioned Open edX named release. + Consequences ************ From 4d973652940834bb42095cc9decdaf3614822cb2 Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Thu, 8 Dec 2022 13:22:23 -0500 Subject: [PATCH 07/14] fix: improving readability --- docs/decisions/0001-namespacing-branches.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index 0f8befe..cfcad59 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -58,11 +58,15 @@ or ``acme/release-candidate-3729`` -In the case of the global namespace, tags and branches may still be further qualified to provide addition information and specificity. +In the case of the global namespace, tags and branches may still be +further qualified to provide additional information and specificity. For example: -``release/palm`` would represent the branch for an officially sanctioned Open edX named release. +``release`` would be consider in the global namespace. + +``release/palm`` would represent the branch for an officially +sanctioned Open edX named release. Consequences From b1441ee28ce17bf603864858e2c0b9499995456a Mon Sep 17 00:00:00 2001 From: Edward Zarecor Date: Thu, 8 Dec 2022 14:12:08 -0500 Subject: [PATCH 08/14] fix: clarify re personal branches. --- docs/decisions/0001-namespacing-branches.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index cfcad59..f86657a 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -77,5 +77,8 @@ Consequences branches and tags 2. Existing branches and tags should be updated to use the new naming protocol -3. A reasonable grace period should be established to schedule and +3. There will be no change to the guidance that personal branches + should be namespaced by GitHub username. For example, the pull + request for this ADR originated in the branch ``e0d/namespace-adr`` +4. A reasonable grace period should be established to schedule and complete the required work From 71f106637c0b7b159ffd2b8c5c7868d1e51ac611 Mon Sep 17 00:00:00 2001 From: Kyle McCormick Date: Wed, 3 Jan 2024 10:21:29 -0500 Subject: [PATCH 09/14] docs: fix typo in branch naming ADR Co-authored-by: Robert Raposa --- docs/decisions/0001-namespacing-branches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index f86657a..03b18d6 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -11,7 +11,7 @@ Context This ADR was written in response to this `Discourse thread`_. -Currently, 2U continuous delevery tooling creates branches and tags +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, From afd96ae1d249bced5f2a1e1d05c0ef4963ff9b45 Mon Sep 17 00:00:00 2001 From: Kyle McCormick Date: Wed, 3 Jan 2024 10:53:50 -0500 Subject: [PATCH 10/14] docs: fix typo in branch naming ADR Co-authored-by: Robert Raposa --- docs/decisions/0001-namespacing-branches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index 03b18d6..e24cbbe 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -63,7 +63,7 @@ further qualified to provide additional information and specificity. For example: -``release`` would be consider in the global namespace. +``release`` would be considered in the global namespace. ``release/palm`` would represent the branch for an officially sanctioned Open edX named release. From 97076a1f1ece5799be7d22033cf2613b7a6cd912 Mon Sep 17 00:00:00 2001 From: Kyle McCormick Date: Wed, 3 Jan 2024 10:54:02 -0500 Subject: [PATCH 11/14] docs: fix typo in branch naming ADR Co-authored-by: Robert Raposa --- docs/decisions/0001-namespacing-branches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index e24cbbe..d2bf93e 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -49,7 +49,7 @@ Decisions 3. The global namespace will be reserved for global project purposes Going forward branches and tags that originate from any specific -organization partipatinging in the Open edX project must by namespaced +organization participating in the Open edX project must by namespaced as follows: ``acme/release`` From 0135fd5f35b7f723688cb4a4ebb5d29efb37b89a Mon Sep 17 00:00:00 2001 From: "Kyle D. McCormick" Date: Mon, 8 Jan 2024 14:37:43 -0500 Subject: [PATCH 12/14] docs: address PR comments --- docs/decisions/0001-namespacing-branches.rst | 59 ++++++++++++-------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index d2bf93e..05beae9 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -41,44 +41,55 @@ time. There are two reasons for that: Decisions ********* -1. We will not forbid project participants with write access to +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. We will require that project participants namespace their branches - and tags to clarify their origin and purpose -3. The global namespace will be reserved for global project purposes - -Going forward branches and tags that originate from any specific -organization participating in the Open edX project must by namespaced + 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: -``acme/release`` +* ``$ORGANIZATION/$PURPOSE`` for organizations. +* ``$GITHUB_USER/$PURPOSE`` for userers. + +For example: -or +* ``acme/release`` +* ``acme/release-candidate-3729`` +* ``acme/our-feature`` +* ``e0d/my-feature`` -``acme/release-candidate-3729`` +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/palm`` would represent the branch for an officially -sanctioned Open edX named release. +* ``release`` would be considered in the global namespace. +* ``release/redwood`` would represent the branch for an officially- + sanctioned Open edX named release. Consequences ************ -1. Continuous delivery systems and other automation should be updated +#. Continuous delivery systems and other automation should be updated across the ecosystem to use the proper naming convention for - branches and tags -2. Existing branches and tags should be updated to use the new naming - protocol -3. There will be no change to the guidance that personal branches - should be namespaced by GitHub username. For example, the pull - request for this ADR originated in the branch ``e0d/namespace-adr`` -4. A reasonable grace period should be established to schedule and - complete the required work + 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. From 63f6cbc0f21bf6d740932e22246ae38c10375137 Mon Sep 17 00:00:00 2001 From: Kyle McCormick Date: Mon, 8 Jan 2024 15:55:04 -0500 Subject: [PATCH 13/14] docs: status --- docs/decisions/0001-namespacing-branches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index 05beae9..b2c9185 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -4,7 +4,7 @@ Namespacing Branches and Tags Status ****** -Draft +Accepted Context ******* From 55e1ba7ff944eab2db7145b7fd8a40f137b85c45 Mon Sep 17 00:00:00 2001 From: Kyle McCormick Date: Mon, 8 Jan 2024 15:55:30 -0500 Subject: [PATCH 14/14] docs: typo, word choice --- docs/decisions/0001-namespacing-branches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0001-namespacing-branches.rst b/docs/decisions/0001-namespacing-branches.rst index b2c9185..594723e 100644 --- a/docs/decisions/0001-namespacing-branches.rst +++ b/docs/decisions/0001-namespacing-branches.rst @@ -55,7 +55,7 @@ organization or user participating in the Open edX project must by namespaced as follows: * ``$ORGANIZATION/$PURPOSE`` for organizations. -* ``$GITHUB_USER/$PURPOSE`` for userers. +* ``$GITHUB_USER/$PURPOSE`` for contributors. For example: