...
While this document and the others on our Wiki site provide a lot of great guidance to developers planning to make contributions to the project, we would ask that developers (and the maintainers/committers) of the project pay particular attention to the following "top 4" practices and adhere to them closely when working on project repositories.
1. Commit subject line messages should explain the problem that the commit is solving in 50 characters or less. “Fixing bug” or “adding comments” doesn’t explain the problem the commit is solving!.
2. Provide a message body to the commit to provide more detail explanation. When you do, keep lines in the body to 72 characters or less.
...
git commit –s –m “This is the subject; keep to 50 char” –m “This is the first line of the message body"$'\n'"This is the second line of the message body."$'\n'"Keep all message lines to 72 char.”
3. Commit your changes in logical chunks. Make it easier for the community to review, comment on, and accept your contribution. For example, create a separate commit for a big fix and an enhancement.
4. Rebase the upstream development branch into your topic branch. Do not merge master into your local PR branch (this is the lazy approach to dealing with committed code locally in a branch, and then realizing that your PR isn’t merge-able because HEAD has changed). See https://git-scm.com/book/en/v2/Git-Branching-Rebasing if you need more help.
...
$ git checkout master |
|---|
8. Merge Rebase the changes from upstream/master into your local master branch. This brings your fork's master branch into sync with the upstream repository, without losing your local changes.
| $ git merge pull --ff-only rebase upstream / master |
|---|
9. Push the updated master back to your fork.
$ git push origin master |
|---|
Note: it was suggested to use git checkout master, then git pull origin master in preference to above (to be discussed).
10. Start new feature.
$ git checkout -b new-feature2 |
|---|
11. Repeat the steps above as appropriate
12. If a change was requested on the new-feature PR then simply rebase your working branch from upstream:
$ git checkout master $ git fetch upstream $ git merge pull --ff-only rebase upstream / master $ git checkout new-feature $ git rebase master |
|---|
13. Make changes.
14. Update the PR killing off the older changes.
...
15. Force push the updated PR back up.
$ git push origin new-feature feature2 –-force |
|---|
By using the --amend and --force options means that any of the commits that you produce should be clean, non-breaking changes at all times that get merged in, instead of having a set of patches in a PR that may have one or two 'fixup' changes.
...
- Anything in the master branch is tested, functioning code that is usable.
- To work on something new, create a descriptively named branch off master (i.e. new-oauth2-scopes).
- Commit to that branch locally and regularly push your work to the same named branch on the server. Rebase regularly from upstream or face the pain of merge conflicts.
- When you need feedback or help, or you think the branch is ready for merging, open a Pull Request.
- A Pull Request is a request that someone else (e.g. an appropriate reviewer such as a project Maintainer or Committer) review the work that you’ve done and merge your changes in. When you create a pull request, you need to select 2 branches on GitHub, the branch that you’ve made your changes on, and the branch where you would want to merge your changes into. Because Pull Requests occur in GitHub, you would need to push your branch to GitHub before you create the request. If they review the changes on your branch and everything looks good, they can just merge the branch (and often delete the branch to clean up). However, if they have questions or comments, they can leave a comment on the pull request, i.e. with changes that you might need to make before they merge in. Then if they needed you to make another change, you can make the change to your code, then commit and push to your existing branch. Because a Pull Request is just a request to merge to branches in GitHub, since you’ve updated your branch, you’ve updated the Pull Request as well. They can then review your latest update and merge in.
- The main rule of GitHub Flow is that master should always be in deployable (usable operational state). GitHub Flow allows and encourages continuous delivery.
- Changes are submitted from developer feature branches as pull-requests against master, then merged using merge commits (which is the default for GitHub merges via their UI).
- When a new version is released, a tag is created, and development continues as before, via pull-requests submitted against master.
- If/when the need for supporting a maintenance release of a specific microservice arises, a branch is created from the required release tag, which is then used for release-specific bug fixes, potentially cherry-picked from master and/or other release branches (if they exist).
...
$ git commit --squash f387cab2 |
|---|
Merging
- Always prefer a rebase to a merge (see above)
- Do not rewrite published history. The repository's history is valuable in its own right and it is very important to be able to tell what actually happened. Altering published history is a common source of problems for anyone working on the project.
- However, there are cases where rewriting history is legitimate. These are when:
- You are the only one working on the branch and it is not being reviewed.
...
- Be consistent. This is related to the workflow but also expands to things like commit messages, branch names and tags. Having a consistent style throughout the repository makes it easy to understand what is going on by looking at the log, a commit message etc.
- Test before you push. Do not push half-done work.
- Use annotated tags for marking releases or other important points in the history. Prefer lightweight tags for personal use, such as to bookmark commits for future reference.
- Keep your repositories at a good shape by performing maintenance tasks occasionally:
1. Commit subject line messages should explain the problem that the commit is solving in 50 characters or less. “Fixing bug” or “adding comments” doesn’t explain the problem the commit is solving!.
2. Provide a message body to the commit to provide more detail explanation. When you do, keep lines in the body to 72 characters or less.
...
git commit –s –m “This is the subject; keep to 50 char” –m “This is the first line of the message body"$'\n'"This is the second line of the message body."$'\n'"Keep all message lines to 72 char.”
3. Commit your changes in logical chunks. Make it easier for the community to review, comment on, and accept your contribution. For example, create a separate commit for a big fix and an enhancement.
4. Rebase the upstream development branch into your topic branch. Do not merge master into your local PR branch (this is the lazy approach to dealing with committed code locally in a branch, and then realizing that your PR isn’t merge-able because HEAD has changed). See https://git-scm.com/book/en/v2/Git-Branching-Rebasing if you need more help.