Docs: Add clarification about git workflow (#13534)

* Docs: Add clarification about git workflow * Update git-workflow.md * Update git-workflow.md * Reword paragraph on merging vs. rebasing * Add references * Add fork section * Clarify link to section "Perform a rebase" * Apply suggestions from code review Co-Authored-By: gziolo <[email protected]>
WordPress · Mar 6, 2019 · d8f0f0c · d8f0f0c
1 parent ffc5b62
commit d8f0f0c
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 8 deletions.
diff --git a/docs/contributors/git-workflow.md 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
@@ -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
@@ -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
@@ -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": []}
 		]},