CONTRIBUTING.md - add some notes about feature branches (#659)

- try nudge people towards using a feature branch in their fork instead of their main.
- add note about squash and merge,
- link to an example PR as a sort of reference.
- add a "Tips" section with some tips.
This commit is contained in:
Andrew Maguire
2023-01-14 21:36:53 +00:00
committed by GitHub
parent bf66b2a890
commit b44305dfbd
+28 -2
View File
@@ -37,20 +37,28 @@ contributions smoothly we recommend the following:
1. Before working on any changes, try to
[sync the forked repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
to keep it up-to-date with the upstream repository.
1. Work on a small focused change that only touches on a few files.
1. On a
[new branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
in your fork (aka a "feature branch" and not `main`) work on a small focused
change that only touches on a few files.
1. Run `pre-commit` and make sure all files have formatting fixed. This
simplifies life for reviewers.
1. Package up a small bit of work that solves part of the problem
[into a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
and
[send it out for review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review).
[Here](https://github.com/LAION-AI/Open-Assistant/pull/658) is an example PR
for this project to illustrate this flow.
1. If you're lucky, we can merge your change into `main` without any problems.
If there's changes to files you're working on, resolve them by:
1. First try rebase as suggested
[in these instructions](https://timwise.co.uk/2019/10/14/merge-vs-rebase/#should-you-rebase).
1. If rebase feels too painful, merge as suggested
[in these instructions](https://timwise.co.uk/2019/10/14/merge-vs-rebase/#should-you-merge).
1. Once you've resolved any conflicts, finish the review and merge into `main`.
1. Once you've resolved any conflicts, finish the review and
[squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits)
your PR (when squashing try to clean up or update the individual commit
messages to be one sensible single one).
1. Merge in your change and move onto a new issue or the second step of your
current issue.
@@ -59,6 +67,24 @@ need help on it or would like suggestions on how to approach the issue. If so,
share wildly. If they seem to have a good handle on it, let them work on their
solution until a challenge comes up.
#### Tips
- At any point you can compare your feature branch to the upstream/main of
`LAION-AI/Open-Assistant` but using a URL like this:
https://github.com/LAION-AI/Open-Assistant/compare/main...andrewm4894:Open-Assistant:my-example-feature-branch.
Obviously just replace `andrewm4894` with your own GitHub user name and
`my-example-feature-branch` with whatever you called the feature branch you
are working on, so something like
`https://github.com/LAION-AI/Open-Assistant/compare/main...<your_github_username>:Open-Assistant:<your_branch_name>`.
This will show the changes that would appear in a PR, so you can check this to
make sure it just looks like only the files you have changed or added will be
part of the PR.
- Try not to work on the `main` branch in your fork - ideally you can keep this
as just a updated copy of `main` from `LAION-AI/Open-Assistant`.
- If your feature branch gets messed up, just update the `main` branch in your
fork and create a fresh new clean "feature branch" you can try again on by
adding your changes one by one in separate commits or all as a single commit.
### When does a review finish
A review finishes when all blocking comments are addressed and at least one