From c95fc709b1b97e85497666e3a2d7133e8b87e46f Mon Sep 17 00:00:00 2001 From: Thomas Fini Hansen Date: Thu, 28 Nov 2024 08:54:16 +0100 Subject: [PATCH 1/5] Document release procedure --- docs/General/README.md | 64 ++--------------- docs/General/documentation-site.md | 69 ++++++++++++++++++ docs/General/release-process.md | 111 +++++++++++++++++++++++++++++ 3 files changed, 185 insertions(+), 59 deletions(-) create mode 100644 docs/General/documentation-site.md create mode 100644 docs/General/release-process.md diff --git a/docs/General/README.md b/docs/General/README.md index 0bfa396..222fca8 100644 --- a/docs/General/README.md +++ b/docs/General/README.md @@ -1,61 +1,7 @@ -# Documentation Site +# General -This project exists to consolidate and standardize documentation across DPL -(Danish Public Libraries) repositories. It's based on [mkdocs -material](https://squidfunk.github.io/mkdocs-material/) and uses a handy -[multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin) to import -markdown and build documentation from other DPL repositories dynamically. -## Adding documentation - -Any repository you want to add to the documentation site, must have a `docs/` -folder in the project root on github and relevant markdown must be moved inside. - -If you wish to further divide your documentation into subfolders, mkdocs will -accomodate this and build the site navigation accordingly. Here is an example: - -``` shell -docs/ -| README.md # Primary docs/index file for your navigation header -└───folder1 # Left pane navigation category -│ │ file01.md -│ └───subfolder1 # Expandable sub-navigation of folder1 -│ │ file02.md -│ │ file03.md -└───folder2 # Additional left pane navigation category - │ file04.md -``` - -The `docs/` folder is self-contained, meaning that any relative links e.g. -`"../../"` linking outside the docs/ directory, should use an absolute URL like: - - -Otherwise, following the link from the documentation site will cause a 404. - -## Site development - -The documentation project is hosted -[here](https://github.com/danskernesdigitalebibliotek/dpl-docs). - -It uses a Github workflow to build and publish to github pages. Since -documentation can be updated independently from other repos, a cron has been -established to publish the site every 6 hours. While this covers most use cases, -it's also possible to trigger it adhoc through [Github -actions](https://github.com/danskernesdigitalebibliotek/dpl-docs/actions/workflows/build-publish.yml) -with the workflow_dispatch event trigger. - -Customizations (colors, font, social links) and general site configuration can -be configured in -[mkdocs.yml](https://github.com/danskernesdigitalebibliotek/dpl-docs/blob/main/mkdocs.yml) - -### Requirements - -- [mkdocs - material](https://squidfunk.github.io/mkdocs-material/getting-started/) -- [multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin) - -### Docker compose setup - -For those not able or wanting to install Python packages on their -machine, there's a rudimentary `docker-compose.yml` file that'll bring -up a container running `mkdocs serve` on the usual HTTP port. +- [Documentation Site](documentation-site) + How to add documentation to this site. +- [DPL CMS release process](release-process) + The steps needed to create a new release of the library sites. diff --git a/docs/General/documentation-site.md b/docs/General/documentation-site.md new file mode 100644 index 0000000..4c1af95 --- /dev/null +++ b/docs/General/documentation-site.md @@ -0,0 +1,69 @@ +# Documentation Site + +This project exists to consolidate and standardize documentation across DPL +(Danish Public Libraries) repositories. It's based on [mkdocs +material](https://squidfunk.github.io/mkdocs-material/) and uses a handy +[multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin) to import +markdown and build documentation from other DPL repositories dynamically. + +## Adding documentation + +### General documentation + +Documentation that isn't specific to any particular repository should +be placed in this [general +section](https://github.com/danskernesdigitalebibliotek/dpl-docs/tree/main/docs/General/). + +### External documentation + +Any repository you want to add to the documentation site, must have a `docs/` +folder in the project root on github and relevant markdown must be moved inside. + +If you wish to further divide your documentation into subfolders, mkdocs will +accomodate this and build the site navigation accordingly. Here is an example: + +``` shell +docs/ +| README.md # Primary docs/index file for your navigation header +└───folder1 # Left pane navigation category +│ │ file01.md +│ └───subfolder1 # Expandable sub-navigation of folder1 +│ │ file02.md +│ │ file03.md +└───folder2 # Additional left pane navigation category + │ file04.md +``` + +The `docs/` folder is self-contained, meaning that any relative links e.g. +`"../../"` linking outside the docs/ directory, should use an absolute URL like: + + +Otherwise, following the link from the documentation site will cause a 404. + +## Site development + +The documentation project is hosted +[here](https://github.com/danskernesdigitalebibliotek/dpl-docs). + +It uses a Github workflow to build and publish to github pages. Since +documentation can be updated independently from other repos, a cron has been +established to publish the site every 6 hours. While this covers most use cases, +it's also possible to trigger it adhoc through [Github +actions](https://github.com/danskernesdigitalebibliotek/dpl-docs/actions/workflows/build-publish.yml) +with the workflow_dispatch event trigger. + +Customizations (colors, font, social links) and general site configuration can +be configured in +[mkdocs.yml](https://github.com/danskernesdigitalebibliotek/dpl-docs/blob/main/mkdocs.yml) + +### Requirements + +- [mkdocs + material](https://squidfunk.github.io/mkdocs-material/getting-started/) +- [multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin) + +### Docker compose setup + +For those not able or wanting to install Python packages on their +machine, there's a rudimentary `docker-compose.yml` file that'll bring +up a container running `mkdocs serve` on the usual HTTP port. diff --git a/docs/General/release-process.md b/docs/General/release-process.md new file mode 100644 index 0000000..10f2956 --- /dev/null +++ b/docs/General/release-process.md @@ -0,0 +1,111 @@ +# Release process + +Creating a new release involves creating a new release of the design +system, the react components and the CMS itself. It's important that +it's done in that order, due to the dependencies between the projects. + +In the following you'll need to use the "Bypass branch protection" +option when merging to skip having someone review the changes. + +# Design system +https://github.com/danskernesdigitalebibliotek/dpl-design-system + +1. Create a pull request from the `develop` branch against `main`. +2. Wait for Github Actions to run and turn green. +3. Merge the pull request. +4. [Create a new +release](https://github.com/danskernesdigitalebibliotek/dpl-design-system/releases/new) + 1. Enter the release version as "Choose a tag", and select to + create it on publish. + 2. Select `main` as target. + 3. Click "Generate release notes" to automatically fill out title + and description. + 4. Ensure that "Set as the latest release" is selected before + publishing the release. + + +# Update DPL React for local development + +These steps are not critical for release, but are required for +developers to get the latest version of the design system when +developing. + +You might not have the required permissions for this step, in that +case, continue to releasing DPL React and return to this later. + +https://github.com/danskernesdigitalebibliotek/dpl-react + +1. Create a new branch locally from `develop` (remember to `git pull` first). +2. Ensure you're using the right version of `node`. You can use `nvm + use` for this. +3. Update the version of the design system used by running `yarn add + @danskernesdigitalebibliotek/dpl-design-system@[version]`, you can + find the latest version of the design system [in the package on + Github](https://github.com/danskernesdigitalebibliotek/dpl-design-system/pkgs/npm/dpl-design-system) + NOTE: You need to be certified for this. +4. Commit and push the changes. +5. Create a pull request from your branch against `develop`. +6. Wait for actions to turn green. +7. Merge the pull request. + +# DPL React + +https://github.com/danskernesdigitalebibliotek/dpl-react + +1. Create a pull request from the `develop` against `main`. +2. Wait for actions to go green. +3. Merge pull request. +4. [Create a new + release](https://github.com/danskernesdigitalebibliotek/dpl-react/releases/new) + in the same way as with the Design system. + +# DPL CMS + +1. Create a new branch locally from `develop` (remember to `git pull` first). +2. Merge `main` into your branch. +3. Update the version of the Design System used: `RELEASE=[version] + VERSION=[version] task dev:composer:update-design-system`. Refer to + `task dev:composer:update-design-system --summary` if needed. +4. Update the version of React components used: `RELEASE=[version] + VERSION=[version] task dev:composer:update-react` +5. Commit, push your branch and create a pull request against `develop`. +6. Wait for actions to go green. +7. Merge your pull request. +8. Create a new pull request from `develop` against `main`. +9. Wait for actions to go green. +10. Merge your pull request. +11. [Create a new + release](https://github.com/danskernesdigitalebibliotek/dpl-cms/releases/new) + in the same way as with the Design system. + +# Deployment to staging + +In order to deploy the new release to staging so that DDF can test it, +refer to [Platform +runbook](../../DPL-Platform/runbooks/how-release-a-new-version-for-approval-testing/). +This will require access to Azure in order to run the deployment. + +# JIRA and communication + +That was the technical part, now you need to tell somebody about your +shiny new release. + +Do the following for both the +[Hermod](https://reload.atlassian.net/jira/software/c/projects/DDFHER/boards/497) +and +[Brahma](https://reload.atlassian.net/jira/software/c/projects/DDFBRA/boards/498) +projecs in Jira (this obviously requires Jira access). + +1. Go into the active sprint board. +2. Select all tickets in the done column which are not tasks and does + not have a fix version (board quick filters can help with this). +3. Add a new fix version with the release version to them (bulk change can help). +4. Mark the release as released. +5. When the release has been [deployed to + staging](#deployment-to-staging), tell DDF by creating a new topic + in the the `#DDF+` Zulip channel with the release name in the + subject and links to the release on staging and the release notes + for the projects that has contributed to the release. Take a look + at past release announcements in Zulip for an + [example](https://reload.zulipchat.com/#narrow/channel/419623-DDF.2B/topic/Release.202024.2E46.2E0/near/482035323) + From 2c4a26031dc6c65966a86f328cc8c75beb550f37 Mon Sep 17 00:00:00 2001 From: Thomas Fini Hansen Date: Mon, 2 Dec 2024 13:27:48 +0100 Subject: [PATCH 2/5] Make headers links --- docs/General/release-process.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/General/release-process.md b/docs/General/release-process.md index 10f2956..4a12afa 100644 --- a/docs/General/release-process.md +++ b/docs/General/release-process.md @@ -7,8 +7,7 @@ it's done in that order, due to the dependencies between the projects. In the following you'll need to use the "Bypass branch protection" option when merging to skip having someone review the changes. -# Design system -https://github.com/danskernesdigitalebibliotek/dpl-design-system +# [Design system](https://github.com/danskernesdigitalebibliotek/dpl-design-system) 1. Create a pull request from the `develop` branch against `main`. 2. Wait for Github Actions to run and turn green. @@ -48,9 +47,7 @@ https://github.com/danskernesdigitalebibliotek/dpl-react 6. Wait for actions to turn green. 7. Merge the pull request. -# DPL React - -https://github.com/danskernesdigitalebibliotek/dpl-react +# [DPL React](https://github.com/danskernesdigitalebibliotek/dpl-react) 1. Create a pull request from the `develop` against `main`. 2. Wait for actions to go green. @@ -59,7 +56,7 @@ https://github.com/danskernesdigitalebibliotek/dpl-react release](https://github.com/danskernesdigitalebibliotek/dpl-react/releases/new) in the same way as with the Design system. -# DPL CMS +# [DPL CMS](https://github.com/danskernesdigitalebibliotek/dpl-cms) 1. Create a new branch locally from `develop` (remember to `git pull` first). 2. Merge `main` into your branch. From e0d119887302ee7b740e18f71b72f7d666e0a3af Mon Sep 17 00:00:00 2001 From: Thomas Fini Hansen Date: Mon, 2 Dec 2024 13:45:08 +0100 Subject: [PATCH 3/5] Update with note about NPM package repository --- docs/General/release-process.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/General/release-process.md b/docs/General/release-process.md index 4a12afa..e6bb686 100644 --- a/docs/General/release-process.md +++ b/docs/General/release-process.md @@ -23,16 +23,17 @@ release](https://github.com/danskernesdigitalebibliotek/dpl-design-system/releas publishing the release. -# Update DPL React for local development +## Update DPL React for local development These steps are not critical for release, but are required for developers to get the latest version of the design system when developing. -You might not have the required permissions for this step, in that -case, continue to releasing DPL React and return to this later. +In order to update the dependencies, you need to be [authenticated +with the GitHub NPM package +repository](https://danskernesdigitalebibliotek.github.io/dpl-docs/DPL-React/#requirements). -https://github.com/danskernesdigitalebibliotek/dpl-react +In https://github.com/danskernesdigitalebibliotek/dpl-react: 1. Create a new branch locally from `develop` (remember to `git pull` first). 2. Ensure you're using the right version of `node`. You can use `nvm From c475ef2836a1cbd8af0fcc38b4a4837f5b957f7f Mon Sep 17 00:00:00 2001 From: Thomas Fini Hansen Date: Mon, 2 Dec 2024 13:53:32 +0100 Subject: [PATCH 4/5] Reorganize release process a bit --- docs/General/release-process.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/General/release-process.md b/docs/General/release-process.md index e6bb686..c5843a6 100644 --- a/docs/General/release-process.md +++ b/docs/General/release-process.md @@ -7,7 +7,9 @@ it's done in that order, due to the dependencies between the projects. In the following you'll need to use the "Bypass branch protection" option when merging to skip having someone review the changes. -# [Design system](https://github.com/danskernesdigitalebibliotek/dpl-design-system) +# Creating the release + +## [Design system](https://github.com/danskernesdigitalebibliotek/dpl-design-system) 1. Create a pull request from the `develop` branch against `main`. 2. Wait for Github Actions to run and turn green. @@ -23,7 +25,7 @@ release](https://github.com/danskernesdigitalebibliotek/dpl-design-system/releas publishing the release. -## Update DPL React for local development +### Update DPL React for local development These steps are not critical for release, but are required for developers to get the latest version of the design system when @@ -48,7 +50,7 @@ In https://github.com/danskernesdigitalebibliotek/dpl-react: 6. Wait for actions to turn green. 7. Merge the pull request. -# [DPL React](https://github.com/danskernesdigitalebibliotek/dpl-react) +## [DPL React](https://github.com/danskernesdigitalebibliotek/dpl-react) 1. Create a pull request from the `develop` against `main`. 2. Wait for actions to go green. @@ -57,7 +59,7 @@ In https://github.com/danskernesdigitalebibliotek/dpl-react: release](https://github.com/danskernesdigitalebibliotek/dpl-react/releases/new) in the same way as with the Design system. -# [DPL CMS](https://github.com/danskernesdigitalebibliotek/dpl-cms) +## [DPL CMS](https://github.com/danskernesdigitalebibliotek/dpl-cms) 1. Create a new branch locally from `develop` (remember to `git pull` first). 2. Merge `main` into your branch. @@ -75,15 +77,19 @@ In https://github.com/danskernesdigitalebibliotek/dpl-react: 11. [Create a new release](https://github.com/danskernesdigitalebibliotek/dpl-cms/releases/new) in the same way as with the Design system. + +# Deployment and announcement + +After creating a release, there's only a few housecleaning tasks left. -# Deployment to staging +## Deployment to staging In order to deploy the new release to staging so that DDF can test it, refer to [Platform runbook](../../DPL-Platform/runbooks/how-release-a-new-version-for-approval-testing/). This will require access to Azure in order to run the deployment. -# JIRA and communication +## JIRA and communication That was the technical part, now you need to tell somebody about your shiny new release. From 9d9ce24f886b8b58df063509f47a6635d49d4dfa Mon Sep 17 00:00:00 2001 From: Thomas Fini Hansen Date: Wed, 11 Dec 2024 13:26:51 +0100 Subject: [PATCH 5/5] Update Jira release management --- docs/General/release-process.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/General/release-process.md b/docs/General/release-process.md index c5843a6..50e927d 100644 --- a/docs/General/release-process.md +++ b/docs/General/release-process.md @@ -100,12 +100,10 @@ and [Brahma](https://reload.atlassian.net/jira/software/c/projects/DDFBRA/boards/498) projecs in Jira (this obviously requires Jira access). -1. Go into the active sprint board. -2. Select all tickets in the done column which are not tasks and does - not have a fix version (board quick filters can help with this). -3. Add a new fix version with the release version to them (bulk change can help). -4. Mark the release as released. -5. When the release has been [deployed to +1. Rename the `upcoming` release to the released version. +2. Mark the release as released. +3. Create a new unrelased `upcoming` release if it doesn't happen automatically. +4. When the release has been [deployed to staging](#deployment-to-staging), tell DDF by creating a new topic in the the `#DDF+` Zulip channel with the release name in the subject and links to the release on staging and the release notes