From c00db8aebf92f17dba02c41a3eca892eaeb4ff69 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Mon, 28 Jan 2019 11:39:37 +0100 Subject: [PATCH 1/8] Docs: Add clarification about git workflow --- docs/contributors/git-workflow.md | 19 +++++++++++++++++++ docs/contributors/repository-management.md | 2 +- docs/manifest.json | 18 ++++++++++++------ docs/toc.json | 3 ++- 4 files changed, 34 insertions(+), 8 deletions(-) create mode 100644 docs/contributors/git-workflow.md diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md new file mode 100644 index 0000000000000..3fa2eb7b0b353 --- /dev/null +++ b/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 +``` diff --git a/docs/contributors/repository-management.md b/docs/contributors/repository-management.md index d4e8df0ebf6aa..67c36d5554435 100644 --- a/docs/contributors/repository-management.md +++ b/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. diff --git a/docs/manifest.json b/docs/manifest.json index e7d2a88e11cc5..494f7df8929e4 100644 --- a/docs/manifest.json +++ b/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", diff --git a/docs/toc.json b/docs/toc.json index cdb3fa096507b..e931429162399 100644 --- a/docs/toc.json +++ b/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": []} ]}, From 72d1f5684ee12a2a6106363f266e6d5407f9632e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20=28Greg=29=20Zi=C3=B3=C5=82kowski?= Date: Tue, 29 Jan 2019 10:27:30 +0100 Subject: [PATCH 2/8] Update git-workflow.md --- docs/contributors/git-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md index 3fa2eb7b0b353..07807297b9e10 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/git-workflow.md @@ -10,10 +10,10 @@ If you have a Pull Request branch that cannot be merged into `master` due to a c 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: +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 origin/master -git push --force-with-lease -u origin you-branch-name +git rebase master +git push --force-with-lease your-branch-name ``` From 8186d103457890ab048703f4711fd9faba32424f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20=28Greg=29=20Zi=C3=B3=C5=82kowski?= Date: Tue, 29 Jan 2019 10:35:24 +0100 Subject: [PATCH 3/8] Update git-workflow.md --- docs/contributors/git-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md index 07807297b9e10..bf9543b1325af 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/git-workflow.md @@ -8,7 +8,7 @@ While it is tempting to merge from `master` into your branch frequently, this le 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`. +Once you have resolved any conflicts locally you can update the Pull Request with `git push --force-with-lease`. Using `--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: From e0b55392f3bcb3f025612426d2863589e7fe837d Mon Sep 17 00:00:00 2001 From: Miguel Fonseca Date: Tue, 29 Jan 2019 11:54:32 +0000 Subject: [PATCH 4/8] Reword paragraph on merging vs. rebasing --- docs/contributors/git-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md index bf9543b1325af..02f995495359d 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/git-workflow.md @@ -4,11 +4,11 @@ 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. +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. -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. +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 at [§ Perform a rebase](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request#perform-a-rebase). -Once you have resolved any conflicts locally you can update the Pull Request with `git push --force-with-lease`. Using `--force-with-lease` parameter is important to guarantee that you don't accidentally overwrite someone else's work. +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: From 4e2996b5e6a8f370047996284fef85bf73203f70 Mon Sep 17 00:00:00 2001 From: Ajit Bohra Date: Wed, 30 Jan 2019 01:48:35 +0530 Subject: [PATCH 5/8] Add references --- docs/contributors/git-workflow.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md index 02f995495359d..1e9f6201cd153 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/git-workflow.md @@ -17,3 +17,7 @@ git fetch git rebase master git push --force-with-lease your-branch-name ``` + +## References +- https://git-scm.com/book/en/v2 +- https://help.github.com/categories/collaborating-with-issues-and-pull-requests/ From 7a92234ccba7cf9cc13d46d50a17ff2cec233b94 Mon Sep 17 00:00:00 2001 From: Ajit Bohra Date: Wed, 30 Jan 2019 02:36:14 +0530 Subject: [PATCH 6/8] Add fork section --- docs/contributors/git-workflow.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md index 1e9f6201cd153..2824196701118 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/git-workflow.md @@ -18,6 +18,27 @@ 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 `fork` and 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 +``` + +Above commands will update your `master` branch from upstream. To update any other branch replace `master` with respective branch. + + ## References - https://git-scm.com/book/en/v2 - https://help.github.com/categories/collaborating-with-issues-and-pull-requests/ From 829c578aa47a17c8eaeac9d998232a267b30296a Mon Sep 17 00:00:00 2001 From: Miguel Fonseca Date: Wed, 30 Jan 2019 14:06:54 +0000 Subject: [PATCH 7/8] Clarify link to section "Perform a rebase" --- docs/contributors/git-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md index 2824196701118..ba980989ac84f 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/git-workflow.md @@ -6,7 +6,7 @@ When many different people are working on a project simultaneously, pull request 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 at [§ Perform a rebase](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request#perform-a-rebase). +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. From 56c3c42c8bcda6eb375e3788482051cd9bd74dc4 Mon Sep 17 00:00:00 2001 From: Stephen Edgar Date: Thu, 31 Jan 2019 10:25:44 +0100 Subject: [PATCH 8/8] Apply suggestions from code review Co-Authored-By: gziolo --- docs/contributors/git-workflow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributors/git-workflow.md b/docs/contributors/git-workflow.md index ba980989ac84f..f159b46126e61 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/git-workflow.md @@ -20,7 +20,7 @@ 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 `fork` and 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. +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: @@ -36,7 +36,7 @@ This will update you local copy to update your fork on github push your changes git push ``` -Above commands will update your `master` branch from upstream. To update any other branch replace `master` with respective branch. +The above commands will update your `master` branch from _upstream_. To update any other branch replace `master` with the respective branch name. ## References