Documentation Changes for Git Usage, Branching Model, and Release Management #713
Conversation
Updating with details applicable for new branching model and to include information from soon-to-be-deleted gitflow.md, in particular on Git pre-commit hook.
Remove in favor of doc/GIT_USAGE.md.
robertbartel
added
documentation
robertbartel
requested review from
hellkite500,
christophertubbs and
aaraney
|
Sure, @christophertubbs, that shouldn't be any trouble. |
Changing rolls and names of branches (master is now integration branch and new "production" branch created to point to latest released code) to cause less disruption to current workflows.
Changing rolls and names of branches (master is now integration/dev branch and new "production" branch created to point to latest released code) to cause less disruption to current workflows.
doc/GIT_USAGE.md
Outdated
| - **production**: the branch representing the latest code verified as production-ready and pointing to the most recently release, official version | ||
| - Most interaction with DMOD repo is done via pull requests (PRs) to the `master` branch | ||
| - Independent branches for features or bug fixes are created off `master` to contain development work that is in progress | ||
| - These branches are reviewed and their changes integrated back into `master` once complete via PRs | ||
| - Typically feature/fix branches exist in personal clones and personal Github forks, but not in the official OWP repo | ||
| - Release branches (e.g., `release-X` for pending version `X`) will periodically be created to finalize the next new version when it is time for it to be released |
There was a problem hiding this comment.
Can you clarify this by stating whether the release branch will be created every release or as needed?
There was a problem hiding this comment.
Sure, I will reword things.
The intent was for a release branch to be created every time there was a new release, to provide a clear, isolated target for testing, QA, etc. But what exactly constitutes "testing, QA, etc." is intentionally undefined for the time being, as is how to decide when it is time to cut the next release.
doc/GIT_USAGE.md
Outdated
| - **production**: the branch representing the latest code verified as production-ready and pointing to the most recently release, official version | ||
| - Most interaction with DMOD repo is done via pull requests (PRs) to the `master` branch | ||
| - Independent branches for features or bug fixes are created off `master` to contain development work that is in progress | ||
| - These branches are reviewed and their changes integrated back into `master` once complete via PRs | ||
| - Typically feature/fix branches exist in personal clones and personal Github forks, but not in the official OWP repo | ||
| - Release branches (e.g., `release-X` for pending version `X`) will periodically be created to finalize the next new version when it is time for it to be released | ||
| - These are managed by the core OWP contributors team |
There was a problem hiding this comment.
Can you emphasize that 99% of people interacting with this repo will not be involved in release or production branches unless they are writing fixes for production releases?
There was a problem hiding this comment.
There's a sign of my own confusion since they won't really be for fixes, but release candidates. Is there any way you can specify or elaborate on that?
There was a problem hiding this comment.
Can you emphasize that 99% of people interacting with this repo will not be involved in release or production branches unless they are writing fixes for production releases?
I am going to add this immediately under the title heading at the top of the file (and also add a bunch of the practical stuff to CONTRIBUTING.md):
Note that this document goes into detail on the Git strategy and branching model for DMOD. It is here for openness and transparency, but many (if not most) users will not need to be concerned with this level of detail. For information geared toward day-to-day development contributions and Git, see the CONTRIBUTING doc.
Does that seem sufficient, or should there also be something here to that effect?
| - Independent branches for features or bug fixes are created off `dev` to contain development work that is in progress | ||
| - These branches are reviewed and their changes integrated back into `dev` once complete via PRs | ||
| - **master**: the main development and integration branch containing the latest completed development work intended for the next released version | ||
| - **production**: the branch representing the latest code verified as production-ready and pointing to the most recently release, official version |
There was a problem hiding this comment.
Can you emphasize that 99% of contributors will not be involved with the production branch? Most devs will be connected to the OWP, so they'd be an OWP contributor, but not an OWP versioner or maintainer.
I think this interaction has been what's caused the most confusion.
Moving more essential, Git-related info needed for code contributions to CONTRIBUTING.md.
Take day-to-day Git contributing stuff out of GIT_USAGE.md and reserve it for things most contributors don't need to know (but are welcome to read about if they want).
|
I think it looks good - thanks for putting up with my nit-picking! |
Modifying and expanding documentation related to release management and new Git branching model.
Additions
RELEASE_MANAGEMENT.mddoc with details on release processRemovals
gitflow.mddoc in favor of usingGIT_USAGE.mdChanges
GIT_USAGE.mdappropriately for move to new branching modelgitflow.md- in particular on pre-commit integration - toGIT_USAGE.mdTesting
Todos
Checklist