This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch add-github-pull-request-guide in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit 76b8df0b08557ea56a95f752e0ec48c883945d37 Author: Maarten Mulders <[email protected]> AuthorDate: Mon Jul 13 20:19:50 2020 +0200 Add short guide "Working with Github pull requests" --- .../apt/developers/welcome-to-new-committers.apt | 2 + .../markdown/developers/github-pull-requests.md | 73 ++++++++++++++++++++++ content/site.xml | 1 + 3 files changed, 76 insertions(+) diff --git a/content/apt/developers/welcome-to-new-committers.apt b/content/apt/developers/welcome-to-new-committers.apt index ad1400d..c99826b 100644 --- a/content/apt/developers/welcome-to-new-committers.apt +++ b/content/apt/developers/welcome-to-new-committers.apt @@ -55,6 +55,8 @@ Guide for new Maven committers * {{{/developers/committer-environment.html}Setup your committer environment}} + * {{{/developers/github-pull-requests.html}Working with pull requests on Github}} + [] And here are the specifics on setting up your Git access: diff --git a/content/markdown/developers/github-pull-requests.md b/content/markdown/developers/github-pull-requests.md new file mode 100644 index 0000000..c604101 --- /dev/null +++ b/content/markdown/developers/github-pull-requests.md @@ -0,0 +1,73 @@ +<!-- +~~ Licensed to the Apache Software Foundation (ASF) under one +~~ or more contributor license agreements. See the NOTICE file +~~ distributed with this work for additional information +~~ regarding copyright ownership. The ASF licenses this file +~~ to you under the Apache License, Version 2.0 (the +~~ "License"); you may not use this file except in compliance +~~ with the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, +~~ software distributed under the License is distributed on an +~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +~~ KIND, either express or implied. See the License for the +~~ specific language governing permissions and limitations +~~ under the License. + +~~ NOTE: For help with the syntax of this file, see: +~~ https://maven.apache.org/doxia/references/apt-format.html +--> + +## Working with Github pull requests + +In the past, patches would come in through JIRA in the form of a patch file. +Nowadays, many contributors start with offering pull requests through [Github](https://github.com/apache). +This short guide describes how to properly integrate those contributions. + +1. Make sure your own copy of the repository is up-to-date with Gitbox. +Also make sure your working copy is "clean" (you have no uncommitted changes or unpushed commits). + +1. Pull requests may multiple commits. +Fetch the whole pull request as a patch file from Github by appending `.patch` to the pull request URL. +Apply the pull request to your own copy using `git am whatever.patch`. + +1. Squash all commits in the pull request into one commit. +[See below](#squashing-commits) for more details. + +1. Make sure the result still fixes the problem at hand. + +1. Finally, push the one squashed commit to the main branch on Gitbox. +It will automatically be pushed to the corresponding branch on Github. + +1. Update administration: + + 1. Close the Github pull request and thank the author for their contribution. + + 1. Also, close the accompanying JIRA ticket, referencing the commit hash that contains the fix. + +### Squashing commits +With `git status` you know how many commits to squash: + + On branch master + Your branch is ahead of 'origin/master' by 6 commits. + (use "git push" to publish your local commits) + +Use that information to do an interactive rebase with `git rebase -i HEAD~6`. +Here, 6 is the number of commits in the pull request. + +This opens up an editor (for example Vim) which a script. +Each commit in the pull request is one line starting with `pick`. +This means the commit should be used in the rebase. + +Edit **all but the first** lines by replacing `pick` with `s` or `squash`. +A _squash_ uses the commit, but melds it into the previous commit. +Save and quit the editor. + +Git will now execute the script you've written. +For squashing, the editor opens again, this time to build the squashed commit. +It will list all individual commits with their commit messages. +The content should be self-explanatory. +Edit the squashed commit, make sure the first line starts with a reference to the JIRA issue, save and quit. + diff --git a/content/site.xml b/content/site.xml index f2cef6b..c2ccfa6 100644 --- a/content/site.xml +++ b/content/site.xml @@ -185,6 +185,7 @@ under the License. <item name="Plugins Retirement Plan" href="/developers/retirement-plan-plugins.html"/> <item name="Maven Dependency Policies" href="/developers/dependency-policies.html"/> <item name="Compatibility Plan" href="/developers/compatibility-plan.html"/> + <item name="Github pull requests" href="/developers/github-pull-requests.html" /> </item> </item> <item name="Books and Resources" href="/articles.html" />
