diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md new file mode 100644 index 00000000000000..f159b46126e617 --- /dev/null +++ b/docs/contributors/git-workflow.md @@ -0,0 +1,44 @@ +# Git Workflow + +## Keeping Your Branch Up To Date + +When many different people are working on a project simultaneously, pull requests can go stale quickly. A "stale" pull request is one that is no longer up to date with the main line of development, and it needs to be updated before it can be merged into the project. + +There are two ways to do this: merging and rebasing. In Gutenberg, the recommendation is to rebase. Rebasing means rewriting your changes as if they're happening on top of the main line of development. This ensures the commit history is always clean and linear. Rebasing can be performed as many times as needed while you're working on a pull request. **Do share your work early on** by opening a pull request and keeping your history rebase as you progress. + +The main line of development is known as the `master` branch. If you have a pull-request branch that cannot be merged into `master` due to a conflict (this can happen for long-running pull requests), then in the course of rebasing you'll have to manually resolve any conflicts in your local copy. Learn more in [section _Perform a rebase_](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request#perform-a-rebase) of _How to Rebase a Pull Request_. + +Once you have resolved any conflicts locally you can update the pull request with `git push --force-with-lease`. Using the `--force-with-lease` parameter is important to guarantee that you don't accidentally overwrite someone else's work. + +To sum it up, you need to fetch any new changes in the repository, rebase your branch on top of `master`, and push the result back to the repository. These are the corresponding commands: + +```sh +git fetch +git rebase master +git push --force-with-lease your-branch-name +``` + +## Keeping Your Fork Up To Date + +Working on pull request starts with forking the Gutenberg repository, your separate working copy. Which can easily go out of sync as new pull requests are merged into the main repository. Here your working repository is a `fork` and the main Gutenberg repository is `upstream`. When working on new pull request you should always update your fork before you do `git checkout -b my-new-branch` to work on a feature or fix. + +To sync your fork you need to fetch the upstream changes and merge them into your fork. These are the corresponding commands: + +``` sh +git fetch upstream +git checkout master +git merge upstream/master +``` + +This will update you local copy to update your fork on github push your changes + +``` +git push +``` + +The above commands will update your `master` branch from _upstream_. To update any other branch replace `master` with the respective branch name. + + +## References +- https://git-scm.com/book/en/v2 +- https://help.github.com/categories/collaborating-with-issues-and-pull-requests/ diff --git a/docs/contributors/repository-management.md b/docs/contributors/repository-management.md index 08b47e1777f2a2..7eaa1cb28661e0 100644 --- a/docs/contributors/repository-management.md +++ b/docs/contributors/repository-management.md @@ -83,7 +83,6 @@ When reviewing issues, here are some steps you can perform: Gutenberg follows a feature branch pull request workflow for all code and documentation changes. At a high-level, the process looks like this: - 1. Check out a new feature branch locally. 2. Make your changes, testing thoroughly. 3. Commit your changes when you’re happy with them, and push the branch. @@ -127,6 +126,7 @@ A pull request can generally be merged once it is: - Vetted against all potential edge cases. - Changelog entries were properly added. - Reviewed by someone other than the original author. +- [Rebased](/docs/contributors/git-workflow.md#keeping-your-branch-up-to-date) onto the latest version of the master branch. The final pull request merge decision is made by the **@wordpress/gutenberg-core** team. diff --git a/docs/manifest.json b/docs/manifest.json index 35964c417ab5ec..6e6dbd2e40251c 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -413,18 +413,24 @@ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/coding-guidelines.md", "parent": "develop" }, - { - "title": "Block Grammar", - "slug": "grammar", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/grammar.md", - "parent": "develop" - }, { "title": "Testing Overview", "slug": "testing-overview", "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/testing-overview.md", "parent": "develop" }, + { + "title": "Git Workflow", + "slug": "git-workflow", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/git-workflow.md", + "parent": "develop" + }, + { + "title": "Block Grammar", + "slug": "grammar", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/grammar.md", + "parent": "develop" + }, { "title": "Scripts", "slug": "scripts", diff --git a/docs/toc.json b/docs/toc.json index 4e06b65d552ce7..14bed66d0a75e7 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -82,8 +82,9 @@ ]}, {"docs/contributors/develop.md": [ {"docs/contributors/coding-guidelines.md": []}, - {"docs/contributors/grammar.md": []}, {"docs/contributors/testing-overview.md": []}, + {"docs/contributors/git-workflow.md": []}, + {"docs/contributors/grammar.md": []}, {"docs/contributors/scripts.md": []}, {"docs/contributors/release.md": []} ]},