From 42250b495bf3879ce9ed8c43fb211b024dd7582b Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 28 Sep 2023 14:07:21 -0400 Subject: [PATCH 1/5] docs: Move OEP-2 to archived. Details about why are in ADR-4 of OEP-55 which is in a follow-on commit. --- .../{best-practices => archived}/oep-0002-bp-repo-metadata.rst | 0 oeps/redirects.txt | 3 ++- 2 files changed, 2 insertions(+), 1 deletion(-) rename oeps/{best-practices => archived}/oep-0002-bp-repo-metadata.rst (100%) diff --git a/oeps/best-practices/oep-0002-bp-repo-metadata.rst b/oeps/archived/oep-0002-bp-repo-metadata.rst similarity index 100% rename from oeps/best-practices/oep-0002-bp-repo-metadata.rst rename to oeps/archived/oep-0002-bp-repo-metadata.rst diff --git a/oeps/redirects.txt b/oeps/redirects.txt index b52aff270..76898d9d2 100644 --- a/oeps/redirects.txt +++ b/oeps/redirects.txt @@ -10,4 +10,5 @@ "processes/oep-0025-proc-incremental-improvements.rst" "archived/oep-0025-proc-incremental-improvements.rst" "architectural-decisions/oep-0023-style-customization.rst" "archived/oep-0023-style-customization.rst" "best-practices/oep-0016-bp-adopt-bootstrap.rst" "archived/oep-0016-bp-adopt-bootstrap.rst" -"architectural-decisions/oep-0014-proc-archive-repos.rst" "processes/oep-0014-proc-archive-repos.rst" \ No newline at end of file +"architectural-decisions/oep-0014-proc-archive-repos.rst" "processes/oep-0014-proc-archive-repos.rst" +"best-practices/oep-0002-bp-repo-metadata.rst" "archived/oep-0002-bp-repo-metadata.rst" From b81fb1a94c476530b3371936571c05a2698e2c8a Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 28 Sep 2023 14:08:41 -0400 Subject: [PATCH 2/5] docs: Change how we track release data. Track release information in the `catalog-info.yaml` file instead of in the `openedx.yaml` file. This will supersede the decision made in OEP-2. --- oeps/archived/oep-0002-bp-repo-metadata.rst | 6 +- ...004-release-data-in-catalog-info-files.rst | 57 +++++++++++++++++++ 2 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst diff --git a/oeps/archived/oep-0002-bp-repo-metadata.rst b/oeps/archived/oep-0002-bp-repo-metadata.rst index 2f613bc94..c3b119532 100644 --- a/oeps/archived/oep-0002-bp-repo-metadata.rst +++ b/oeps/archived/oep-0002-bp-repo-metadata.rst @@ -15,12 +15,16 @@ OEP-2: Repository Metadata * - Arbiter - Calen Pennington * - Status - - Accepted + - Replaced * - Type - Best Practice * - Created - 2016-04-21 +.. warning:: + + This OEP has been replaced with :doc:`/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files`. + Abstract ******** diff --git a/oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst b/oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst new file mode 100644 index 000000000..c6c585536 --- /dev/null +++ b/oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst @@ -0,0 +1,57 @@ +0004 Release Data in catalog-info.yaml +###################################### + +Status +****** + +**Accepted** + +Context +******* + +* Currently we have 2 high-level metadata files that will live in every repo. The ``openedx.yaml`` file and the ``catalog-info.yaml`` file. + +* The only information in ``openedx.yaml`` that is still useful and kept up-to-date is ``release`` tag that tells you what repos are part of the twice-annual Open edX release. + +Decision +******** + +We will use metadata in the ``catalog-info.yaml`` file to determine whether or not a repository is going to be tagged for Open edX releases. + +Specification +************* + +The data will be housed in a new annotation by the name of ``openedx.org/release``. Non-null values of this key will indicate the branch that should be tagged for releases. + +.. code-block:: yaml + :caption: Annotating that the ``master`` branch should be tagged for new releases. + + metadata: + annotations: + openedx.org/release: "master" + +.. code-block:: yaml + :caption: Annotating that the ``main`` branch should be tagged for new releases. + + metadata: + annotations: + openedx.org/release: "main" + +.. code-block:: yaml + :caption: Annotating that no branch should be tagged for new releases. This is the same as if the annotation was not added in the first place but more explicit. + + metadata: + annotations: + openedx.org/release: null + + +Consequences +************ + +* :doc:`/archived/oep-0002-bp-repo-metadata` will be marked as superseded as it contains no more useful data. + +* `Tooling related to the release `_ will need to be updated. + +* Useful release data in the current ``openedx.yaml`` files will need to be migrated to the relevant catalog-info.yaml files. + +* Any examples of ``catalog-info.yaml`` will need to be updated to include an example of the new annotation. From d050c2e368ed006b4f0f5b0065761a1b74b35573 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 28 Sep 2023 14:13:49 -0400 Subject: [PATCH 3/5] docs: Update documents as a consequence of OEP-55:ADR-4 --- .../oep-0010-proc-openedx-releases.rst | 44 +++++-------------- ...1-use-backstage-to-support-maintainers.rst | 3 ++ 2 files changed, 15 insertions(+), 32 deletions(-) diff --git a/oeps/processes/oep-0010-proc-openedx-releases.rst b/oeps/processes/oep-0010-proc-openedx-releases.rst index 921815d8b..80e0494ec 100644 --- a/oeps/processes/oep-0010-proc-openedx-releases.rst +++ b/oeps/processes/oep-0010-proc-openedx-releases.rst @@ -144,39 +144,13 @@ Releases will be tagged "open-release/RELEASENAME.1", Involving repos in the Open edX build process ============================================= -:doc:`OEP-2 ` defines a file format for repository metadata. The -``openedx-release`` key is an optional dictionary governing the participation -of the repo in the Open edX release process. - -Repos for applications and IDAs that are part of the Open edX software need to -have the ``openedx-release`` key. Libraries that are part of Open edX do not -need the key, because they will be pulled in by whatever component uses them as -a dependency. - -``openedx-release``: dictionary (optional) - - Possible keys: - - ``ref`` - The name of the release-from branch in this repo. This is the branch - that will be tagged when an Open edX release is made. - - ``maybe`` - A boolean, but only ever "true" if present. This key is created by the - repo initialization tool (cookiecutter). If it is present, the repo - will be skipped during releases, but will be flagged so the release - manager can start a conversation with the repo owner to determine if - the repo should be included. - - Obsolete keys: - - ``requirements`` - This key is obsolete, and can be removed. - - ``parent-repo`` - This key is obsolete. It was used by libraries. Repos marked with this - key should have the entire ``openedx-release`` key removed. +:doc:`/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files` +defines annotations the ``catalog-info.yaml`` metadata file that can be used to +indicate that a repo needs to be tagged for releases. +Details can be found in the above ADR but in summary there will be a new catalog +annotation by the name of ``openedx.org/release`` that will indicate whether or +not a given repo should be tagged for Open edX releases. Installing Open edX =================== @@ -200,6 +174,12 @@ There are two supported installation methods: Change History ************** +2023-09-28 +========== + +* Reference catalog-info.yaml instead of OEP-2 for where we store + release metadata. + 2022-02-24 ========== diff --git a/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst b/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst index fb0960344..fd5cb3a22 100644 --- a/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst +++ b/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst @@ -123,6 +123,9 @@ References # names that might be interested in changes to the architecture of this # component. openedx.org/arch-interest-groups: "feanil" + # (Optional) We use the below annotation to indicate whether or not this + # repository should be tagged for openedx releases and which branch is tagged. + openedx.org/release: "main" spec: # (Required) This can be a group (`group:`) or a user (`user:`). From 298ea3f3b31b1e41a14c38613b62d9cc0fe338c4 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 28 Sep 2023 14:15:16 -0400 Subject: [PATCH 4/5] docs: Other minor docs cleanup. --- .../decisions/0001-use-backstage-to-support-maintainers.rst | 2 +- oeps/processes/oep-0055/decisions/0003-readme-specification.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst b/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst index fd5cb3a22..208f25a7b 100644 --- a/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst +++ b/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst @@ -4,7 +4,7 @@ Status ****** -**Provisional** +**Accepted** Context ******* diff --git a/oeps/processes/oep-0055/decisions/0003-readme-specification.rst b/oeps/processes/oep-0055/decisions/0003-readme-specification.rst index 45e942f36..1c1bdec25 100644 --- a/oeps/processes/oep-0055/decisions/0003-readme-specification.rst +++ b/oeps/processes/oep-0055/decisions/0003-readme-specification.rst @@ -4,7 +4,7 @@ Status ****** -** Accepted ** +**Accepted** Context ******* From 065015e3034a0fcebae9025e933616b0831df13f Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 28 Sep 2023 16:49:08 -0400 Subject: [PATCH 5/5] docs: Update oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst Co-authored-by: Ned Batchelder --- .../decisions/0004-release-data-in-catalog-info-files.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst b/oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst index c6c585536..26a69bfd7 100644 --- a/oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst +++ b/oeps/processes/oep-0055/decisions/0004-release-data-in-catalog-info-files.rst @@ -11,7 +11,7 @@ Context * Currently we have 2 high-level metadata files that will live in every repo. The ``openedx.yaml`` file and the ``catalog-info.yaml`` file. -* The only information in ``openedx.yaml`` that is still useful and kept up-to-date is ``release`` tag that tells you what repos are part of the twice-annual Open edX release. +* The only information in ``openedx.yaml`` that is still useful and kept up-to-date is the ``release`` tag that tells you what repos are part of the twice-annual Open edX release. Decision ********