From b44305dfbd12a12133e1457788f5f5c338b61d36 Mon Sep 17 00:00:00 2001 From: Andrew Maguire Date: Sat, 14 Jan 2023 21:36:53 +0000 Subject: [PATCH] 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. --- CONTRIBUTING.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b290f5fe..56dfa22c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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...:Open-Assistant:`. + 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