[
https://issues.apache.org/jira/browse/OPENNLP-1045?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16064961#comment-16064961
]
ASF GitHub Bot commented on OPENNLP-1045:
-----------------------------------------
Github user jfrazee commented on a diff in the pull request:
https://github.com/apache/opennlp-site/pull/21#discussion_r124300001
--- Diff: src/main/jbake/content/using-git.ad ---
@@ -0,0 +1,178 @@
+////
+ 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.
+////
+= Using Git
+:jbake-type: page
+:jbake-tags: maven
+:jbake-status: published
+:idprefix:
+
+There are several ways to setup Git for committers and contributors.
Contributors can safely setup Git any way they
+choose but committers should take extra care since they can push new
commits to the master at Apache and various
+policies there make backing out mistakes problematic. Therefore all but
very small changes should go through a PR,
+even for committers. To keep the commit history clean take note of the use
of `--squash` below when merging into
+`apache/master`.
+
+## Git setup for Committers
+
+This describes setup for one local repo and two remotes. It allows you to
push the code on your machine to either your
+GitHub repo or to Git at Apache (i.e. git-wip-us.apache.org). You will
want to fork GitHub's apache/opennlp to your own
+account on GitHub, this will enable Pull Requests of your own. Cloning
this fork locally will set up "origin" to point
+to your remote fork on GitHub as the default remote. So if you perform
"git push origin master" it will go to GitHub.
+
+To attach to the apache Git repo do the following:
+
+ git remote add apache
https://git-wip-us.apache.org/repos/asf/opennlp.git
+
+To check your remote setup:
+
+ git remote -v
+
+You should see something like this:
+
+ origin https://github.com/your-github-id/opennlp.git (fetch)
+ origin https://github.com/your-github-id/opennlp.git (push)
+ apache https://git-wip-us.apache.org/repos/asf/opennlp.git (fetch)
+ apache https://git-wip-us.apache.org/repos/asf/opennlp.git (push)
+
+Now if you want to experiment with a branch, this by default points to
your GitHub account because "origin" is default.
+You can work as you normally do using just GitHub, until you are ready to
merge with the Apache remote repository.
+Some conventions will integrate with Apache JIRA ticket numbers.
+
+ git checkout -b opennlp-xxxx #xxxx typically is a JIRA ticket number
+ #do some work on the branch
+ git commit -a -m "doing some work"
+ git push origin opennlp-xxxx # notice pushing to **origin** not
**apache**
+
+Once you are ready to commit to the Apache remote you can merge and push
them directly, or better yet create a
+pull request (PR).
+
+## How to create a PR (committers)
+
+Push your branch to GitHub:
+
+ git checkout opennlp-xxxx
+ git push origin opennlp-xxxx
+
+Go to your opennlp-xxxx branch on GitHub. Since you forked it from
GitHub's apache/opennlp it will default any PR to
+go to apache/master.
+
+* Click the green "Compare, review, and create pull request" button.
+* You can edit the _to_ and _from_ for the PR if it is not correct. The
"base fork" should be apache/opennlp unless
+you are collaborating separately with one of the committers on the list.
The "base" will be master. Do not submit a
+PR to one of the other branches unless you know what you are doing. The
"head fork" will be your forked repo and the
+"compare" will be your opennlp-xxxx branch.
+* Click the "Create pull request" button and name the request
"OPENNLP-XXXX" (uppercase). This will connect the
+comments of the PR to the mailing list and JIRA comments.
+* From now on the PR lives on GitHub's apache/opennlp. You can use the
commenting UI there.
+* If you are looking for a review or sharing with someone else say so in
the comments but do not worry about
+automated merging of your PR -- you will have to do that later. The PR is
tied to your branch so you can respond to
+comments, fix code, and commit from your local repository. They will
appear on the PR page and be mirrored to JIRA
+and to the mailing list.
+
+When you are satisfied and want to push it to Apache's remote repository
proceed with **Merging a PR**
+
+## How to create a PR (contributors)
+
+Create pull requests: <<anchor-1,[1]>>.
+
+Pull requests are made to apache/opennlp repository on GitHub. In the
GitHub UI you should pick the master
+branch to target the PR as described for committers. This will be reviewed
and commented on so the merge is
+not automatic. This can be used for discussing a contributions in progress.
+
+## Merging a PR (yours or contributors)
+
+Start with reading <<anchor-2,[2]>> (merging locally).
+
+Remember that pull requests are equivalent to a remote GitHub branch with
potentially a multitude of commits.
+In this case it is recommended to squash remote commit history to have one
commit per issue, rather
+than merging in a multitude of contributor's commits. In order to do that,
as well as close the PR at the
+same time, it is recommended to use **squash commits**.
+
+Merging pull requests is equivalent to a "pull" of a contributor's branch:
+
+ git checkout master # switch to local master branch
+ git pull apache master # fast-forward to current remote HEAD
+ git pull --squash https://github.com/cuser/opennlp cbranch # merge to
master
+
+`--squash` ensures all PR history is squashed into single commit, and
allows committer to use his/her own
--- End diff --
@kinow @kottmann I think it might be worth considering using `git am
--signoff` on top of this. So contributor rebases and squash against master
just prior to merge (sometimes having the multiple commits during review is
helpful) and then the merge by a committer is with `--signoff` which ensures
the contributor gets credit, but also the git history reflects who signed off
and performed the merge.
> Add documentation for development with Git (at ASF, GitHub, etc) for OpenNLP
> ----------------------------------------------------------------------------
>
> Key: OPENNLP-1045
> URL: https://issues.apache.org/jira/browse/OPENNLP-1045
> Project: OpenNLP
> Issue Type: Documentation
> Components: Website
> Reporter: Bruno P. Kinoshita
> Assignee: Bruno P. Kinoshita
> Priority: Minor
> Labels: development, documentation, git, website
> Attachments: OPENNLP-1045-menu-20170516.png,
> OPENNLP-1045-page-20170516-fullpage.png
>
>
> We need to add documentation for developers, explaining the process to work
> with Git in Apache OpenNLP.
> Listing things like proper way to commit (e.g. include JIRA issue whenever
> possible in the commit message), how to handle and merge pull requests (e.g.
> empty commits, merge with fast-forward, etc), and so it goes.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
