You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@opennlp.apache.org by kinow <gi...@git.apache.org> on 2017/05/18 08:25:10 UTC

[GitHub] opennlp-site pull request #11: OPENNLP-1045: Git documentation for developer...

GitHub user kinow opened a pull request:

    https://github.com/apache/opennlp-site/pull/11

    OPENNLP-1045: Git documentation for developers

    Add documentation for development with Git (at ASF, GitHub, etc) for OpenNLP.
    
    Inspired mainly at the Cordova docs [1]. Did not include `--squash` option, which the Mahout docs mention [2] as I never used it :-)
    
    Feel free to submit suggestions or update the pull request if you have access to.
    
    Cheers
    Bruno
    
    [1] https://github.com/apache/cordova-coho/blob/master/docs/processing-pull-requests.md
    [2] https://mahout.apache.org/developers/github.html

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/kinow/opennlp-site OPENNLP-1045-1

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/opennlp-site/pull/11.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #11
    
----

----


---
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.
---

[GitHub] opennlp-site pull request #11: OPENNLP-1045: Git documentation for developer...

Posted by kottmann <gi...@git.apache.org>.

Github user kottmann commented on a diff in the pull request:

https://github.com/apache/opennlp-site/pull/11#discussion_r123445407

--- Diff: src/main/jbake/content/using-git.ad ---
@@ -0,0 +1,113 @@
+////
+ 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:
+
+## Introduction
+
+The Apache OpenNLP project has a series of rules that every developer must adhere to. The contents in this page
+can be helpful even to experienced developers, as it includes information about merging GitHub pull requests
+programmatically, which is not an easy task, or sometimes users are more familiar with the web interface.
+
+Simple rules include always merging pull requests with the fast-forward, using a JIRA ticket ID in the commit message
+whenever possible, and always squashing pull requests. Also, changes are verified by a build server, so developers
+must remember to check if all tests pass, as well as other quality checks such as code style.
+
+## Cloning the OpenNLP Git repository
+
+After obtaining committership to OpenNLP, you probably want to submit your changes to the project source repository.
+This section contains the steps that every committer must follow, in order to make sure every developer is following
+the workflow, and have a consistent and simple commit tree.
+
+ git clone https://git-wip-us.apache.org/repos/asf/opennlp.git
+ cd opennlp
+ git config user.name "Your Name"
+ git config user.email "your-email"
+ git config merge.ff only
+
+You can also clone the project web site repository.
+
+ https://git-wip-us.apache.org/repos/asf/opennlp.git
+ # repeat remaining steps as above
+
+In order to test your commit rights, and following a project tradition, normally the first commit of every new
+member is to add his/her name to the list of project members. Look for the `team.ad` source file in the web site
+repository, add your name, and try sending your first commit.
+
+For a complete list of the project repositories, visit the link:/source-code.html[Source Code] section.
+
+## Merging Pull Requests
+
+This section documents the process of merging code changes contributed via
+link:https://help.github.com/articles/about-pull-requests/[Github Pull Requests]. It is important to
+remember to **always merge with link:https://git-scm.com/docs/git-merge[fast-forward]**. If you followed the steps in
+the first section, your local working copy should be already configured for that. Otherwise, remember to use `ff-only`
+when merging.
+
+### Adding a remote repository pointing to GitHub
+
+In order to fetch the pull requests in GitHub, you need to add a remote repository.
+
+ git remote add github https://github.com/apache/opennlp.git
+ git fetch --all
+ git fetch github pull/<PULL-ID>/head:<BRANCHNAME>
+ git checkout <BRANCHNAME>
+
+Replacing `<PULL-ID>` by the GitHub pull request ID (you can find it in the pull request URL) and `<BRANCHNAME>` by
+the name of the new local branch. If you have suggestions to enhance or fix the pull request, send your comments via
+the GitHub user interface, or add a comment to the JIRA ticket &mdash; if any.
+
+Once you are happy with the changes, you can check out the master branch, and merge the pull request. Remember
+to make sure the **branch has been rebase'd against master**, and also that all tests pass.
+
+ git checkout master
+ git merge --ff-only <BRANCHNAME>
+ git push origin master
+
+In case other commits happened after the pull request was submitted, you must ask the user to rebase the pull
+request against the master branch, and squash his commit. An alternative for that, is to rebase and squash the commits
+yourself, when there is no feedback from the user.
+
+ git checkout <BRANCHNAME>
+ git rebase master
+ # squash and amend the commit message if necessary...
+ git checkout master
+ git merge --ff-only <BRANCHNAME>
+ git push origin master
+
+### Stale Pull Requests
+
+You can automatically close a pull request when merging, by amending the commit message. Make sure to use the following
+syntax in your commit message.
+
+ Merging branch <BRANCHNAME>
+ OPENNLP-<JIRA-ID>: This closes #<PULL-ID>
--- End diff --

here we usually write closes #xyz and that's it, preferable not in the subject line

---
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.
---

[GitHub] opennlp-site issue #11: OPENNLP-1045: Git documentation for developers

Posted by kinow <gi...@git.apache.org>.

Github user kinow commented on the issue:

    https://github.com/apache/opennlp-site/pull/11
  
    @smarthi I remember you had some Git docs from Mahout (I think) that you thought we should use too. Are you happy too with us using this version in this pull request for now, and then start working on top of 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.
---

[GitHub] opennlp-site pull request #11: OPENNLP-1045: Git documentation for developer...

Posted by kottmann <gi...@git.apache.org>.

Github user kottmann commented on a diff in the pull request:

https://github.com/apache/opennlp-site/pull/11#discussion_r123445203

We only accept PRs that have a single commit, then we don't have to deal with that during merging.

[GitHub] opennlp-site pull request #11: OPENNLP-1045: Git documentation for developer...

Posted by kinow <gi...@git.apache.org>.

Github user kinow commented on a diff in the pull request:

https://github.com/apache/opennlp-site/pull/11#discussion_r123445212

Good point. Let me re-write that quickly now (will squash commits too)

[GitHub] opennlp-site pull request #11: OPENNLP-1045: Git documentation for developer...

Posted by kinow <gi...@git.apache.org>.

Github user kinow commented on a diff in the pull request:

https://github.com/apache/opennlp-site/pull/11#discussion_r123446411

Oh, my mistake. The OPENNLP-<JIRA-ID> was supposed to be on the line above where it is now.

[GitHub] opennlp-site pull request #11: OPENNLP-1045: Git documentation for developer...

Posted by kottmann <gi...@git.apache.org>.

Github user kottmann commented on a diff in the pull request:

https://github.com/apache/opennlp-site/pull/11#discussion_r123445064

The easiest thing is to rebase yourself, the contributor only needs to be involved if there are conflicts.