doctrine-website
doctrine-website copied to clipboard
doctrine
WIP: maintenance workflow documentation
This is a stub of the release process that I was slowly putting into words.
As discussed with @carusogabriel and @Majkl578 while at PHP Central Europe, we need to get this automated, and removed from the documentation once that's done (as in: documentation just references the release tool)
TODO:
- [ ] check how this actually renders
- [ ] document code review as part of the maintenance workflow
- [ ] document dependency upgrades as part of the maintenance workflow
- [ ] document signed tags for releases
@jwage can you please talk about this workflow with @doctrine/team-mongodb-odm? I think ORM and ODM are quite different right now, but if we build an automation, we should unify the workflows.
@SenseException I marked it as WIP because it is incomplete, but I don't remember what's missing. Can you check it again, please?
I think the biggest difference is that ODM's version description is usually linking to CHANGELOG.md which contains description of what changed (and we usually craft it manually). And I personally use github to tag a new release instead of console :)
I think the biggest difference is that ODM's version description is usually linking to
CHANGELOG.md
Good one! What do we do about CHANGELOG.md? I think we should start maintaining it, especially requiring an entry in it for every relevant patch. If we can ensure that, then the release notes (and therefore the git tag message) can be inferred from the latest block in CHANGELOG.md. Should I add it to the document?
And I personally use github to tag a new release instead of console :)
We need signed tags for our releases, especially with the size of our audience. This isn't feasible via Github UI...
So in ODM we always write an entry in CHANGELOG before tagging new release, they usually look like this - list there not always contains all PRs merged, because some are not worthy mentioning (i.e. docs). Sometimes we put more info to the changelog, that usually happens for a minor release (like this one).
Bugfix release notes follow this scheme (copy-paste-fix links):
Maintenance release.
Please see [changelog](https://github.com/doctrine/mongodb-odm/blob/1.2.x/CHANGELOG-1.2.md#125-2018-07-20) for a complete list of fixes.
All issues and pull requests in this release may be found under the [1.2.5 milestone](https://github.com/doctrine/mongodb-odm/issues?q=milestone%3A1.2.5).
We need signed tags for our releases, especially with the size of our audience. This isn't feasible via Github UI...
I can change my ways, no problem :+1:
I can change my ways, no problem +1
I don't want to impede your work, hence my strong focus on automation in this documentation. At some point, I'd like to remove humans from the release process in this organisation.
I can change my ways, no problem +1
I don't want to impede your work, hence my strong focus on automation in this documentation. At some point, I'd like to remove humans from the release process in this organisation.
That was about signing tags and not using github UI ;) FWIW I think maintaing changelog is better as it's easily grep-able.
I think this should also work well for changes in the documentation. @Ocramius Do we need to emphasize that changes in the documentation shouldn't be in the same commits as code changes? Also: New features should get a proper documentation before they can be merged.
shouldn't be in the same commits as code changes?
I don't mind if the commits overlap or not, but they should probably be in the same patch. I don't think it has to do with the maintenance workflow though: we can put it in issue/PR templates, maybe?
Folks, I can't get to work on this further in the next weeks: is anybody in @doctrine/team-documentation willing to finish this up?
