Document release procedure #67
Conversation
docs/General/README.md
Outdated
There was a problem hiding this comment.
Please reconsider this restructure.
As far as I can tell this PR injects a new subdirectory General into /docs. I wonder why that is necessary. I do not see it mentioned in commit comments or in the PR. As I see it the current /docs structure is sufficient.
There was a problem hiding this comment.
Because each markdown file in the docs directory shows up in the header. So by now we'd have something like:
As I believe that there'll be more cross repo documentation added over time the header will get cramped. Besides I don't think that having these kind of things top-level makes sense from a information structure viewpoint.
I did play a bit with mkdocs settings and liked turning off the top-level tabs, but that was too major a change for me to dare suggesting.
| ## 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. |
There was a problem hiding this comment.
With this info in mind I suggest reverting docs/General/documentation-site.md to docs/README.md. Having this documented within docs/General seems to defeat the purpose of the instructions.
There was a problem hiding this comment.
Eh, why? The purpose of the instructions is to tell anyone interested in adding to the documentation how to do it. Why should this be the very first thing people see when visiting? I'd hope that most visitors is visiting to read documentation, not just looking for how to add to it.
docs/General/release-process.md
Outdated
| # Design system | ||
| https://github.com/danskernesdigitalebibliotek/dpl-design-system |
There was a problem hiding this comment.
| # Design system | |
| https://github.com/danskernesdigitalebibliotek/dpl-design-system | |
| ## [Design system](https://github.com/danskernesdigitalebibliotek/dpl-design-system) |
docs/General/release-process.md
Outdated
| You might not have the required permissions for this step, in that | ||
| case, continue to releasing DPL React and return to this later. |
There was a problem hiding this comment.
Consider adding a link to https://danskernesdigitalebibliotek.github.io/dpl-docs/DPL-React/#requirements which describes how to authenticate against the GitHub NPM repository.
Currently the wording is not totally clear here. You might read it specific GitHub permissions might be needed or the like but it is really something anyone working with DPL React would be able to do.
docs/General/release-process.md
Outdated
| publishing the release. | ||
|
|
||
|
|
||
| # Update DPL React for local development |
There was a problem hiding this comment.
| # Update DPL React for local development | |
| ## Update DPL React for local development |
docs/General/release-process.md
Outdated
| # DPL React | ||
|
|
||
| https://github.com/danskernesdigitalebibliotek/dpl-react |
There was a problem hiding this comment.
| # DPL React | |
| https://github.com/danskernesdigitalebibliotek/dpl-react | |
| ## [DPL React](https://github.com/danskernesdigitalebibliotek/dpl-react) |
docs/General/release-process.md
Outdated
| release](https://github.com/danskernesdigitalebibliotek/dpl-react/releases/new) | ||
| in the same way as with the Design system. | ||
|
|
||
| # DPL CMS |
There was a problem hiding this comment.
| # DPL CMS | |
| ## [DPL CMS](https://github.com/danskernesdigitalebibliotek/dpl-cms) |
docs/General/release-process.md
Outdated
| release](https://github.com/danskernesdigitalebibliotek/dpl-cms/releases/new) | ||
| in the same way as with the Design system. | ||
|
|
||
| # Deployment to staging |
There was a problem hiding this comment.
| # Deployment to staging | |
| ## Deployment to staging |
docs/General/release-process.md
Outdated
| 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 |
There was a problem hiding this comment.
| # JIRA and communication | |
| ## JIRA and communication |
There was a problem hiding this comment.
Don't agree with the last two, deployment and kommunication isn't part of DPL CMS.
Maybe there should be two H1s: "Creating the release" and "Deployment and announcement", where we move the current headlines in under.
Add release process documentation.