opennlp-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kottmann <...@git.apache.org>
Subject [GitHub] opennlp-site pull request #21: OPENNLP-1045: Add Git development page (adapt...
Date Tue, 27 Jun 2017 15:21:22 GMT
Github user kottmann commented on a diff in the pull request:

    https://github.com/apache/opennlp-site/pull/21#discussion_r124306989
  
    --- 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 --
    
    I personally think it is best if the contributor just gives us the commits we can include
without any modification in master (expect a rebase) in a PR.
    
    @jfrazee do you think this makes a too high entry barrier for new contributors? One problem
I see with that is that it requires some git skills, and if people don't know it well they
have a hard time doing that.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message