Docs: Add clarification about git workflow

docs/contributors/git-workflow.md

@@ -0,0 +1,19 @@
+# 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.
+
+While it is tempting to merge from `master` into your branch frequently, this leads to a messy history because each merge creates a merge commit. When working by yourself, it is best to use `git pull --rebase master`, but if you're pushing to a shared repo, it is best to not do any merging or rebasing until the feature is ready for testing, and then do a [rebase](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request) at the very end. This is one reason why it is important to open pull requests whenever you have working code.
+
+If you have a Pull Request branch that cannot be merged into `master` due to a conflict (this can happen for long-running Pull Request discussions), it's still best to rebase the branch (rather than merge) and resolve any conflicts on your local copy. 
+
+Once you have resolved any conflicts locally you can update the Pull Request with `git push --force-with-lease`. 
+
+This is how you can bring your branch up to date with the latest changes from `master` branch:
+
+```sh
+git fetch
+git rebase origin/master
+git push --force-with-lease -u origin you-branch-name
+```

docs/contributors/repository-management.md

@@ -85,7 +85,6 @@ When reviewing the issue backlog, 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.
@@ -129,6 +128,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.
 

docs/manifest.json

@@ -407,18 +407,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",

docs/toc.json

@@ -81,8 +81,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": []}
 		]},