You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2012/12/14 22:12:00 UTC
svn commit: r1422093 - in /isis/site/trunk/content: ./ contributors/
contributors/resources/
Author: danhaywood
Date: Fri Dec 14 21:11:51 2012
New Revision: 1422093
URL: http://svn.apache.org/viewvc?rev=1422093&view=rev
Log:
isis site - tidying up the git/contribution pages
Added:
isis/site/trunk/content/contributors/contributing.md
- copied, changed from r1419259, isis/site/trunk/content/contributors/git-workflow.md
isis/site/trunk/content/contributors/development-environment.md
- copied, changed from r1421105, isis/site/trunk/content/contributors/building-isis.md
isis/site/trunk/content/contributors/git-cookbook.md
- copied, changed from r1421105, isis/site/trunk/content/contributors/using-git.md
isis/site/trunk/content/contributors/git-policy.md
isis/site/trunk/content/contributors/resources/git-workflow-2.png (with props)
isis/site/trunk/content/contributors/resources/git-workflow.png (with props)
isis/site/trunk/content/contributors/resources/git-workflow.pptx (with props)
isis/site/trunk/content/contributors/resources/github-cloning.png (with props)
isis/site/trunk/content/contributors/resources/github-forking.png (with props)
Removed:
isis/site/trunk/content/contributors/building-isis.md
isis/site/trunk/content/contributors/git-workflow.md
isis/site/trunk/content/contributors/using-git.md
Modified:
isis/site/trunk/content/contributors/about.md
isis/site/trunk/content/contributors/release-process.md
isis/site/trunk/content/documentation.md
Modified: isis/site/trunk/content/contributors/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/about.md?rev=1422093&r1=1422092&r2=1422093&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/about.md (original)
+++ isis/site/trunk/content/contributors/about.md Fri Dec 14 21:11:51 2012
@@ -2,9 +2,10 @@ Title: Contributors
### Contributors
-- [Building Isis](building-isis.html)
-- [Using Git](using-git.html)
-- [Git Workflow](git-workflow.html)
+- [Contributing](contributing.html)
+- [Development Environment](development-environment.html)
+- [Git Policy](git-policy.html)
+- [Git Cookbook](git-cookbook.html)
- [Coding Conventions](coding-conventions.html)
- [Versioning Policy](versioning-policy.html)
Copied: isis/site/trunk/content/contributors/contributing.md (from r1419259, isis/site/trunk/content/contributors/git-workflow.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/contributing.md?p2=isis/site/trunk/content/contributors/contributing.md&p1=isis/site/trunk/content/contributors/git-workflow.md&r1=1419259&r2=1422093&rev=1422093&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/git-workflow.md (original)
+++ isis/site/trunk/content/contributors/contributing.md Fri Dec 14 21:11:51 2012
@@ -1,40 +1,55 @@
-Title: git workflow
+Title: Contributing
This page explains how you can contribute to Apache Isis. Thanks for considering to help out, your contributions are appreciated!
-*There is some overlap between this material and that in [Using Git](using-git.html) page. We intend to merge the two pages; for now, please read both.*
+## Workflow
-##Identify Work
+Isis' source code is hosted in an Apache git repo ([https](https://git-wip-us.apache.org/repos/asf/isis.git), [http](http://git-wip-us.apache.org/repos/asf/isis.git)), with a clone on github ([https](https://github.com/apache/isis.git), [ssh](git@github.com:apache/isis.git)).
-[JIRA](https://issues.apache.org/jira/browse/ISIS) and the [mailing lists](http://isis.apache.org/support.html) are great places to start. If you have your own ideas to improve or extend Isis it's a good practice to create a ticket in JIRA and/or discuss this in the mailing lists. You probably get some useful feedback and support.
+As you might imagine, only committers are permitted to push changes to the central git repo. As a contributor, we recommend that you fork the [apache/isis](https://github.com/apache/isis.git) repo in github, and then use your fork as a way of publishing your patches for the Isis committers to apply.
-##Clone the Isis source code
+The diagram below illustrates the process:
-Isis' source code is hosted in an Apache git repo ([https](https://git-wip-us.apache.org/repos/asf/isis.git), [http](http://git-wip-us.apache.org/repos/asf/isis.git)), with a clone on github ([https](https://github.com/apache/isis.git), [ssh](git@github.com:apache/isis.git)).
+<img src="resources/git-workflow.png" width="600px"></img>
+That is:
-**If you are a committer** then you can clone directory from the Apache git repo:
+- as a one-time activity, you fork the [github.com/apache/isis](https://github.com/apache/isis.git) repo into your own fork on github.com
+- as a one-time activity, you clone your fork to your local computer
+- you set the [github.com/apache/isis](https://github.com/apache/isis.git) as your upstream branch; this will allow you to keep your local clone up-to-date with new commits
+ - note the asymmetry here: the `upstream` repo (the Apache github repo) is **not** the same as the `origin` repo (your fork).
+- you work on your changes locally; when done, you push them to your github fork
-<pre>
-git clone https://git-wip-us.apache.org/repos/asf/isis.git apache-isis
-cd apache-isis
-git checkout -t origin/master
-</pre>
+The diagram also indicates the [JIRA](https://issues.apache.org/jira/browse/ISIS) ticket; all work in Isis should tracked in JIRA. Before you decide to start hacking with Isis, it's always worth creating a ticket in JIRA and then have a discussion about it on the [mailing lists](http://isis.apache.org/support.html).
-This will set up your local `master` branch as a tracking branch of the `origin/master` branch.
+Assuming you have a JIRA ticket, generally speaking all you need to do once you have your patch is to add a comment with the URL to your patch on your github fork; the Isis committer can then pull down your change.
+As a slight simplification to the above, you may decide to clone directly from [github.com/apache/isis](https://github.com/apache/isis.git) rather than create your own fork:
-**If you are not a committer** but would like to contribute patches then the easiest thing is probably to create a fork in github. You use this fork to (a) provide an initial copy of the code, and (b) provide a place to share your changes with the project maintainers, generating patches etc.
+<img src="resources/git-workflow-2.png" width="600px"></img>
-You can create a fork through the github website; you'll end up with a repo called something like `https://github.com/yourname*/isis.git`. Once created, you should clone your new fork to your computer. On Windows, use github's 'Clone in Windows' feature; on Mac/Linux create a clone from the command line:
+In this case your `upstream` repo is the same as your `origin` repo, which might seem more straightforward. On the other hand, if you go this route then you'll need create patches locally and attach them to the JIRA ticket.
-<pre>
-git clone https://github.com/<i>yourname</i>/isis.git apache-isis
-cd apache-isis
-git checkout master
-</pre>
+For the Isis committers it really doesn't matter which route you take, so go with whatever's most comfortable.
+
+### Setting up your fork/clone
+
+If you choose to create your own fork then you'll need an account on [github.com](https://github.com). You then fork simply by pressing the "Fork" button:
+
+<img src="resources/github-forking.png" width="600px"></img>
+
+An account isn't needed if you just clone straight from the [github.com/apache/isis](http://github.com/apache/isis).
+
+Whether you've forked or not, you then need to clone the repo onto your computer. Github makes this very easy to do:
-What you'll also want to do is to add a remote to the original Apache Isis repo that you forked. This remote is traditionally called `upstream`. You should then arrange for your `master` branch to track the `upstream/master` remote branch:
+* for Windows users, we suggest you use github's 'Clone in Windows' feature
+* for Mac/Linux users, create a clone from the command line:
+
+Again, the info is easily found in the github page:
+
+<img src="resources/github-cloning.png" width="600px"></img>
+
+If you've created your own fork, then you need to add the `upstream` remote to the [github.com/apache/isis](https://github.com/apache/isis). This remote is traditionally called `upstream`. You should then arrange for your `master` branch to track the `upstream/master` remote branch:
<pre>
git remote add upstream https://github.com/apache/isis.git
@@ -42,24 +57,44 @@ git pull upstream
git branch --set-upstream master upstream/master
</pre>
-You can now fetch any more recent commits from the upstream repo using simply:
+If you didn't create your own fork, you can omit the above step. Either way around, you can now fetch new commits using simply:
<pre>
git fetch
</pre>
-Because you've just created your fork, most likely the upstream's `master` branch will be the same as your local `master` and your github fork's `origin/master` (all three will point to the same commit). Use `gitk --all` to confirm.
-
For more info on tracking branches [here](http://git-scm.com/book/en/Git-Branching-Remote-Branches) and [here](http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html).
-##Sample Git Workflow
+##Commit messages
+
+Although with git your commits are always performed on your local repo, those commit messages become public when the patch is applied by an Isis committer. You should take time to write a meaningful commit message that helps explain what the patch refers to; if you don't then there's a chance that your patch may be rejected and not applied. No-one likes hard work to go to waste!
+
+We therefore recommend that your commit messages are as follows [1]:
+
+<pre>
+ISIS-999: Make the example in CONTRIBUTING imperative and concrete
+
+Without this patch applied the example commit message in the CONTRIBUTING
+document is not a concrete example. This is a problem because the
+contributor is left to imagine what the commit message should look like
+based on a description rather than an example. This patch fixes the
+problem by making the example concrete and imperative.
+
+The first line is a real life imperative statement with a ticket number
+from our issue tracker. The body describes the behavior without the patch,
+why this is a problem, and how the patch fixes the problem when applied.
+</pre>
+
+Once your git repo is setup, the next thing you'll most likely want to do is to setup your development environment. See [here](development-environment.html) for more details.
-For this example, suppose that you've decided to work on JIRA ticket #123, an enhancement to support Blob/Clob datatypes.
+##Sample Contribution Workflow
-#### Update your master branch
+Assuming you're development environment is all setup, let's walk through how you might make contribute a patch. In this example, suppose that you've decided to work on JIRA ticket #123, an enhancement to support Blob/Clob datatypes.
-We're assuming you have cloned the Isis repository as per the example above. Let's first make sure your fork is up-to-date, by retrieving new commits from upstream repo and then merging them as a fast-forward into your local branch.
+### Update your master branch
-If a committer, your upstream is simply the `origin`. If not a committer, your upstream is the `upstream` remote. In either case, because your local `master` branch is tracking the appropriate remote's `master` branch, the same commands work:
+The first thing to do is to make sure your local clone is up-to-date. We do this by retrieving new commits from upstream repo and then merging them as a fast-forward into your local branch.
+
+Irrespective of whether you are using a github fork, the upstream for your local `master` branch will be tracking the appropriate remote's `master` branch. So n either case, the same commands work:
<pre>
git checkout master
@@ -73,10 +108,9 @@ git checkout master
git pull --ff-only
</pre>
-If the `merge` or `pull` fails, it means that you must have made commits and there have been changes meanwhile on the remote `master`'s branch. Use `gitk --all` to confirm. There's a procedure below to retrospectively sort out this situation.
-
+If the `merge` or `pull` fails, it means that you must have made commits and there have been changes meanwhile on the remote `master`'s branch. You can use `gitk --all` to confirm. If this fails, see our [git cookbook](git-cookbook.html) page for a procedure to retrospectively sort out this situation.
-#### Create a topic branch
+### Create a topic branch
We recommend you name topic branches by the JIRA ticket, ie <tt>ISIS-nnn-description</tt>. So let's create a new branch based off `master` and call it "ISIS-123-blobs"
@@ -96,7 +130,7 @@ The command line prompt should also indi
###Make File Changes and Commit
-Next, make changes to your files using the usual commands:
+Next, make changes to your files using the usual commands (see also our [git cookbook](git-cookbook.html) page):
* `git add`
* `git mv`
@@ -121,11 +155,7 @@ git pull --ff-only
These are the same commands that you would have run before you created your topic branch. If you use `gitk --all`, there's a good chance that new commits have come in.
-If you are a committer, you'll see that the remote `origin/master` has most likely advanced. If you are not a committer, you'll similarly see that the remote `upstream/master` has advanced. (For non-committers, the `origin/master` won't ever advance because this is simply your fork taken a while back).
-
-Because you've been working in a topic branch, your local `master` branch and the remote `master` branch's should be pointing to the same commit.
-
-Next, we reintegrate our topic branch by rebasing onto master:
+Next, we reintegrate our topic branch by rebasing onto `master`:
<pre>
git checkout ISIS-123-blobs
git rebase master
@@ -133,51 +163,41 @@ git rebase master
This takes all of the commits in your branch, and applies them on top of the new `master` branch. When your change is eventually integrated back in, it will result in a nice clear linear history on the public repo.
-### Committers only: pushing the changes
-
-**If you are a committer**, you can now simply do a fast forward merge of master, and then push the changes:
-
-<pre>
-git checkout master
-git merge --ff-only ISIS-123-blobs
-git push
-</pre>
+If the rebase fails because of a conflict, then you'll be dumped into REBASE mode. Edit the file that has the conflict, and make the appropriate edits. Once done:
-Because the `master` branch is a direct ancestor of the topic branch, the fast-forward merge should work. The `git push` then pushes those changes back to the master Isis repo.
-
-To clean up, you can delete your topic branch:
<pre>
-git branch -d ISIS-123-blobs
+git add <i>filename</i>
+git rebase --continue
</pre>
-And committers are done.
+Once the rebase has completed, re-run your tests to confirm that everything is still good.
-### Non-committers: Making your branch available remotely
+### Making your change available remotely (with fork)
-For non-committers, your changes must be applied by a project maintainer. So what you need to do is make those code changes available for review. This is where your Github fork comes in.
+If you have your own fork, you can now simply push the changes you've made locally to your fork:
-Make sure you've checked out your topic branch, and the push the changes to github (`origin` remote):
<pre>
git checkout ISIS-123-blobs
git push -u origin ISIS-123-blobs
</pre>
This will create a corresponding branch in the remote github repo. If you use `gitk --all`, you'll also see a `remotes/origin/ISIS-123-blobs` branch.
-With your topic branch onto your fork, an Isis maintainer can review and merge the topic branch into the main repository.
+Then, update your JIRA and add a comment with a URL to this branch.
-The easiest way to inform the Isis maintainer is by raising a *pull request* in Github. Pull requests sent to the Apache GitHub repositories should forward a pull request e-mail to the [dev mailing list](../support.html), so we recommend that you sign up to the dev mailing list first before issuing your pull request.
+You can aso use github to raise a *pull request*. Pull requests sent to the Apache GitHub repositories will forward a pull request e-mail to the [dev mailing list](../support.html); sign up to the dev mailing list first before issuing your pull request.
-To raise the pull request:
+The process to raise the pull request:
-* Open a web browser to your GitHub account's Isis fork.
-* Select your topic branch so that the pull request references the topic branch.
-* Click the Pull Request button.
-* Notifying the Mailing List
+* Open a web browser to your github fork of isis
+* Select your topic branch (pushed in the previous step) so that the pull request references the topic branch.
+* Click the `Pull Request` button.
+* Check that the Isis mailing list email came through.
-Assuming you've already subscribed to the dev mailing list, you can check that your request came through.
+### Making your change available remotely (no fork)
+If you decided against having your own github fork, then you'll need to create a patch and then attach to the JIRA. Use `github diff` and redirect to a file.
-####If your pull request is accepted
+##If your pull request is accepted
To double check that your pull request is accepted, update your `master` branch from the `upstream` remote:
@@ -195,16 +215,16 @@ git branch -D ISIS-123-blobs
git push origin --delete ISIS-123-blobs
</pre>
-Finally, you probably want to push the latest changes in master back up to github.
+Finally, you might want to push the latest changes in master back up to your github fork. If so, use:
<pre>
git checkout master
git push origin master
</pre>
-####If your pull Request is rejected
+####If your pull request is rejected
-In this case, you just need to update your branch from the main repository and then address the rejection reason.
+If your pull request is rejected, then you'll need to update your branch from the main repository and then address the rejection reason.
<pre>
git checkout master
@@ -221,26 +241,5 @@ git push origin --delete ISIS-123-blobs
... and continue as before until you are ready to resubmit your change.
-## If you've accidentally worked on `master` branch
-
-If at any time the `git pull` from your upstream fails, it most likely means that you must have made commits on the `master` branch. You can use `gitk --all` to confirm; at some point in time both `master` and `origin\master` will have a common ancestor.
-
-You can retrospectively create a topic branch for the work you've accidentally done on `master`.
-
-First, create a branch for your current commit:
-<pre>
-git branch <i>newbranch</i>
-</pre>
-
-Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:
-
-<pre>
-git stash
-</pre>
-
-Finally, locate the shaId of the commit you want to roll back to (easily obtained in `gitk -all`), and wind `master` branch back to that commit:
-<pre>
-git checkout master
-git reset --hard <i>shaId</i> # move master branch shaId of common ancestor
-</pre>
-
+----
+[1] inspiration for the recommended commit format comes from the [puppet](https://github.com/puppetlabs/puppet) project's [contributing](https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md) page.
\ No newline at end of file
Copied: isis/site/trunk/content/contributors/development-environment.md (from r1421105, isis/site/trunk/content/contributors/building-isis.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/development-environment.md?p2=isis/site/trunk/content/contributors/development-environment.md&p1=isis/site/trunk/content/contributors/building-isis.md&r1=1421105&r2=1422093&rev=1422093&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/building-isis.md (original)
+++ isis/site/trunk/content/contributors/development-environment.md Fri Dec 14 21:11:51 2012
@@ -1,27 +1,116 @@
-Title: Building Isis
+Title: Development Environment
+#### Installing Git
-## Introduction
+The easiest place to get hold of command-line git is probably the [github download page](http://git-scm.com/downloads).
-Check out the Isis source code as documented [here](using-git.html).
+On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:
-Install Maven 3.0.x, downloadable [here](http://maven.apache.org/download.html).
+<img src="resources/setting-up-git.png" width="400px"></img>
-Set `MAVEN_OPTS` environment variable:
+Once git is installed, the two main command line tools to note are:
+
+- `git` command line tool
+- `gitk` for viewing the commit history
+
+Three commands in particular worth knowing:
+
+<pre>git help <i>command</i></pre>
+
+ will open the man page in your web browser
+
+<pre>git gui</pre>
+
+ will open up a basic GUI client to staging changes and making commits
+
+<pre>gitk --all</pre>
+
+ will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.
+
+If using Windows, note that github also have a dedicated [Windows client](https://help.github.com/articles/set-up-git). With a little [hacking around](http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx), it can also be made to work with non-github repositories.
+
+If using Mac, you might also want to check out Atlassian's [Sourcetree](http://www.atlassian.com/software/sourcetree/overview).
+
+
+
+#### Cloning the Isis repo and Configuring
+
+First, clone the Isis repo. If you are **not a committer**, please see the [contributing](contributing.html) page for details on which repo to clone from.
+
+**Committers**, meanwhile, should clone from the Apache read/write repo:
<pre>
-MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=128m
+git clone https://git-wip-us.apache.org/repos/asf/isis.git
+</pre>
+
+You should then configure your user name and password; see also [Apache's git](https://git-wip-us.apache.org/) docs:
+
+<pre>
+git config user.name "<i>My Name Here</i>"
+git config user.email <i>myusername@apache.org</i>
</pre>
+And, you should also configure the `core.autocrlf` so that line endings are normalized to LF (Unix style) in the rep; again see [Apache's git](https://git-wip-us.apache.org/) page:
-Build using:
+- on Windows, use:
+<pre>git config core.autocrlf auto
+</pre>
+- on Mac/Linux, use:
<pre>
-mvn clean install
+git config core.autocrlf input
+</pre>
+
+The Windows setting means that files are converted back to CRLF on checkout; the Mac/Linux setting means that the file is left as LF on checkout.
+
+We also recommend setting `core.safecrlf`, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:
+
+<pre>
+git config core.safecrlf true
</pre>
+Note that these settings are supplemented in the repo by the `.gitattributes` file and that explicitly specifies line handling treatment for most of the common file types that we have.
+
+One final configuration that we recommend is for `git pull` to perform a rebase by default, rather than a merge. This results in a linear log history. If you want to explicitly have branches in the history, then you can always create a topic branch, discussed below:
+<pre>
+git config branch.autosetuprebase always
+</pre>
+
+If you don't use git outside of Apache, you can add the `--global` flag so that the above settings apply for all repos managed by git on your PC.
+
+For further reading, see:
+
+- [git config man page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html)
+- [.gitattributes man page](http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html)
+- [.gitattributes git-scm.com docs](http://git-scm.com/docs/gitattributes)
+
+
+## Installing Maven
+
+Install Maven 3.0.x, downloadable [here](http://maven.apache.org/download.html).
+
+Set `MAVEN_OPTS` environment variable:
+
+<pre>
+MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=128m
+</pre>
+
+
<!--
TODO: x-ref importing-projects
TODO: x-ref sharing projects
-->
+
+
+
+
+## Building the Source Code
+
+To build the source code, simply go to the root directory and type:
+
+<pre>
+mvn clean install
+</pre>
+
+Alternatively, you can go to the root of any of the components (eg as documented [here](release-process.html) and build each individually.
\ No newline at end of file
Copied: isis/site/trunk/content/contributors/git-cookbook.md (from r1421105, isis/site/trunk/content/contributors/using-git.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/git-cookbook.md?p2=isis/site/trunk/content/contributors/git-cookbook.md&p1=isis/site/trunk/content/contributors/using-git.md&r1=1421105&r2=1422093&rev=1422093&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/using-git.md (original)
+++ isis/site/trunk/content/contributors/git-cookbook.md Fri Dec 14 21:11:51 2012
@@ -1,129 +1,12 @@
-Title: Using Git
+Title: Git Cookbook
-*There is some overlap between this material and that in [Git workflow](git-workflow.html). We intend to merge the two pages; for now please read both.*
+This page describes the commands often used while working with git.
-## Introduction
-
-These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
-
-- git commits form an acyclic graph, with each commit pointing to its parent commit (or commit**s**, if a merge)
-
-- a branch is merely a pointer to one of these commits; git calls the main branch `master`
-
-- git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.
-
-For more background reading, see:
-
-- [Pro Git](http://git-scm.com/book) book (free in electronic form)
-- [Git community book](https://github.s3.amazonaws.com/media/book.pdf)
-- [git reset demystified](http://git-scm.com/2011/07/11/reset.html) - differentiating the working directory vs index/staging area
-
-And, of course, there is loads of good advice on [stackoverflow.com](http://stackoverflow.com/questions/tagged/git)
-
-## General principle
-
-There are many ways of using Git, but the only real prescriptive advice here is that commits should only have one parent. Doing this keeps the commit history clean; even though work actually happens in parallel, in the commit history it will look like all work was done serially.
-
-This is accomplished using `git rebase`; the idea being that any changes that you make locally are re-applied on top of the latest fetch from the `master` branch. Many other projects also work this way; a good write-up of how SpringSocial use git can be found [here](https://github.com/SpringSource/spring-social/wiki/Contributing).
-
-## Basics
-
-#### Installing Git
-
-The easiest place to get hold of command-line git is probably the [github download page](http://git-scm.com/downloads).
-
-On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:
-
-<img src="resources/setting-up-git.png" width="500px"></img>
-
-
-Once git is installed, the two main command line tools to note are:
-
-- `git` command line tool
-- `gitk` for viewing the commit history
-
-Three commands in particular worth knowing:
-
-<pre>git help <i>command</i></pre>
-
- will open the man page in your web browser
-
-<pre>git gui</pre>
-
- will open up a basic GUI client to staging changes and making commits
-
-<pre>gitk --all</pre>
-
- will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.
-
-If using Windows, note that github also have a dedicated [Windows client](https://help.github.com/articles/set-up-git). With a little [hacking around](http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx), it can also be made to work with non-github repositories.
-
-If using Mac, you might also want to check out Atlassian's [Sourcetree](http://www.atlassian.com/software/sourcetree/overview).
-
-
-#### Cloning the Isis repo and Configuring
-
-First, clone the Isis repo:
-
-<pre>
-git clone https://git-wip-us.apache.org/repos/asf/isis.git
-</pre>
-
-As per [Apache's Git page](https://git-wip-us.apache.org/), you should then configure your user name and password:
-
-<pre>
-git config user.name "<i>My Name Here</i>"
-git config user.email <i>myusername@apache.org</i>
-</pre>
-
-And (again as recommended by [Apache's Git page](https://git-wip-us.apache.org/)), you should also configure the `core.autocrlf` so that line endings are normalized to LF (Unix style) in the repo.
-
-- on Windows, use:
-<pre>git config core.autocrlf auto
-</pre>
-
-- on Mac/Linux, use:
-<pre>
-git config core.autocrlf input
-</pre>
-
-The Windows setting means that files are converted back to CRLF on checkout; the Mac/Linux setting means that the file is left as LF on checkout.
-
-We also recommend setting `core.safecrlf`, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:
-
-<pre>
-git config core.safecrlf true
-</pre>
-
-Note that these settings are supplemented in the repo by the `.gitattributes` file and that explicitly specifies line handling treatment for most of the common file types that we have.
-
-One final configuration that we recommend is for `git pull` to perform a rebase by default, rather than a merge. This results in a linear log history. If you want to explicitly have branches in the history, then you can always create a topic branch, discussed below:
-<pre>
-git config branch.autosetuprebase always
-</pre>
-
-If you don't use git outside of Apache, you can add the `--global` flag so that the above settings apply for all repos managed by git on your PC.
-
-For further reading, see:
-
-- [git config man page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html)
-- [.gitattributes man page](http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html)
-- [.gitattributes git-scm.com docs](http://git-scm.com/docs/gitattributes)
-
-#### Commit message format
-
-Commit messages should follow the format:
-
-<pre>
-ISIS-nnn: brief summary here
-
-- optionally, longer details
-- should be written here
-- in bullet points
-</pre>
-
-where `ISIS-nnn` is a ticket raised in our [JIRA issue tracker](https://issues.apache.org/jira/browse/ISIS).
+In addition to these basic commands, please make sure you have read:
+* [development environment](development-environment.html)
+* [git policy](git-policy.html)
+* [contributing](contributing.html)
#### Modifying existing files
@@ -174,11 +57,13 @@ git commit -m "ISIS-nnn: yada yada"
</pre>
-## Common Workflows
+## Common Workflows (Committers only)
-### Working on master
+The [contributing](contributing.html) page describes the workflow for non-committers. This section is therefore primarily for the benefit of Isis **committers**.
-With this option, you do nothing special locally, just commit to the `master` branch.
+### Working on `master`
+
+The easiest way of working is to make your commits directly on your local `master`. This is perhaps somewhat hacky, but acceptable for very small changes.
When you are ready to push your changes, use:
@@ -344,3 +229,33 @@ git push origin master --force
</pre>
If this doesn't work, it may be that the remote repo has disabled this feature. There are other hacks to get around this, see for example [here](http://stackoverflow.com/questions/1377845/git-reset-hard-and-a-remote-repository).
+
+
+
+
+
+## If you've accidentally worked on `master` branch
+
+If at any time the `git pull` from your upstream fails, it most likely means that you must have made commits on the `master` branch. You can use `gitk --all` to confirm; at some point in time both `master` and `origin\master` will have a common ancestor.
+
+You can retrospectively create a topic branch for the work you've accidentally done on `master`.
+
+First, create a branch for your current commit:
+<pre>
+git branch <i>newbranch</i>
+</pre>
+
+Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:
+
+<pre>
+git stash
+</pre>
+
+Finally, locate the shaId of the commit you want to roll back to (easily obtained in `gitk -all`), and wind `master` branch back to that commit:
+<pre>
+git checkout master
+git reset --hard <i>shaId</i> # move master branch shaId of common ancestor
+</pre>
+
+
+
Added: isis/site/trunk/content/contributors/git-policy.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/git-policy.md?rev=1422093&view=auto
==============================================================================
--- isis/site/trunk/content/contributors/git-policy.md (added)
+++ isis/site/trunk/content/contributors/git-policy.md Fri Dec 14 21:11:51 2012
@@ -0,0 +1,49 @@
+Title: Git Policy
+
+## Introduction
+
+These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
+
+- git commits form an acyclic graph, with each commit pointing to its parent commit (or commit**s**, if a merge)
+
+- a branch is merely a pointer to one of these commits; git calls the main branch `master`
+
+- git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.
+
+For more background reading, see:
+
+- [Pro Git](http://git-scm.com/book) book (free in electronic form)
+- [Git community book](https://github.s3.amazonaws.com/media/book.pdf)
+- [git reset demystified](http://git-scm.com/2011/07/11/reset.html) - differentiating the working directory vs index/staging area
+
+And, of course, there is loads of good advice on [stackoverflow.com](http://stackoverflow.com/questions/tagged/git)
+
+## General principle
+
+There are many ways of using Git, but the only real prescriptive advice here is:
+
+**commits should only have one parent**.
+
+Doing this keeps the commit history clean; even though work actually happens in parallel, in the commit history it will look like all work was done serially.
+
+This is accomplished using `git rebase`; the idea being that any changes that you make locally are re-applied on top of the latest fetch from the `master` branch. The [cookbook](git-cookbook.html) page describes how to do this in detail.
+
+Many other projects also work this way; a good write-up of how SpringSocial use git can be found [here](https://github.com/SpringSource/spring-social/wiki/Contributing).
+
+## Commit message
+
+#### Commit message format
+
+The minimum we expect in a commit messages is:
+
+<pre>
+ISIS-nnn: brief summary here
+
+- optionally, longer details
+- should be written here
+- in bullet points
+</pre>
+
+where `ISIS-nnn` is a ticket raised in our [JIRA issue tracker](https://issues.apache.org/jira/browse/ISIS).
+
+For non-committers we typically expect more detail again; see the [contributing](contributing.html) page for the longer format recommended for contributors to use.
\ No newline at end of file
Modified: isis/site/trunk/content/contributors/release-process.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/release-process.md?rev=1422093&r1=1422092&r2=1422093&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/release-process.md (original)
+++ isis/site/trunk/content/contributors/release-process.md Fri Dec 14 21:11:51 2012
@@ -123,11 +123,11 @@ For example, if releasing `core` version
<version>1.2.3-SNAPSHOT</version>
</pre>
-### Update Apache parent (Isis Core only)
+### Update parent (Isis Core)
If releasing Isis Core, check (via [http://search.maven.org](http://search.maven.org)) whether there is a newer version of the Apache parent `org.apache:apache`.
-If there is, update the `<version>` in the `<parent>` element in the parent POM `org.apache.isis.core:isis`:
+If there is, update the `<version>` in the `<parent>` element in the parent POM to match the newer version:
<pre>
<parent>
@@ -140,6 +140,34 @@ If there is, update the `<version>` in t
where `NN` is the updated version number.
+### Update parent (non core components)
+
+If releasing a non-core component, then check and if necessary update the `<version>` in the `<parent>` element in the parent POM to match the released (non-SNAPSHOT) version of `org.apache.isis.core:isis`:
+
+<pre>
+<parent>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis</artifactId>
+ <version>1.2.3</version>
+ <relativePath></relativePath>
+</parent>
+</pre>
+
+{note
+This obviously requires that the core has been released previously. If you
+also releasing core at the same time as the component, then you will need to go through the release process for core first, then come back round to release the component.
+}
+
+Also, if there is a tck test module with `oa.isis.core:isis-core-tck` as its parent, then make sure that it is also updated.
+
+All components have a small handful of modules, so it's probably easiest to load up and inspect each in turn:
+
+<pre>
+vi `find . -name pom.xml | grep -v target`
+</pre>
+
+... and search for `SNAPSHOT`.
+
### Update dependency versions
The `maven-versions-plugin` should be used to determine if there are newer versions of any of Isis' dependencies. Since this goes off to the internet, it may take a minute or two to run:
@@ -284,25 +312,7 @@ Confirm that the versions of the Isis ar
### Sanity check for non-`core` components
-First, check that there are *NO SNAPSHOT* dependencies in any of the `pom.xml` of the modules of the component.
-
-In particular, in the root pom of the component, ensure that *the version of core specified as the parent is correct and IS NOT A SNAPSHOT*. For example:
-
-<pre>
-<parent>
- <groupId>org.apache.isis.core</groupId>
- <artifactId>isis</artifactId>
- <version>1.2.3</version>
- <relativePath></relativePath>
-</parent>
-</pre>
-
-{note
-This obviously requires that the core has been released previously. If you
-also releasing core at the same time as the component, then you will need to go through the release process for core first, then come back round to release the component.
-}
-
-Also, if there is a tck test module with `oa.isis.core:isis-core-tck` as its parent, then make sure that it is also updated.
+You should already have changed the parent POM of the releasable module to reference a released version of `org.apache.isis.core:isis`. Now, also check that there are remaining *NO SNAPSHOT* dependencies in any of the `pom.xml` of the modules of the component.
Next, delete all Isis artifacts from your local Maven repo:
Added: isis/site/trunk/content/contributors/resources/git-workflow-2.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/git-workflow-2.png?rev=1422093&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/git-workflow-2.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/contributors/resources/git-workflow.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/git-workflow.png?rev=1422093&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/git-workflow.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/contributors/resources/git-workflow.pptx
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/git-workflow.pptx?rev=1422093&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/git-workflow.pptx
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/contributors/resources/github-cloning.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/github-cloning.png?rev=1422093&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/github-cloning.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/contributors/resources/github-forking.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/github-forking.png?rev=1422093&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/github-forking.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1422093&r1=1422092&r2=1422093&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Fri Dec 14 21:11:51 2012
@@ -44,9 +44,10 @@ Title: Documentation
### Contributors
-- [Building Isis](contributors/building-isis.html)
-- [Using Git](contributors/using-git.html)
-- [Git Workflow](contributors/git-workflow.html)
+- [Contributing](contributors/contributing.html)
+- [Development Environment](contributors/development-environment.html)
+- [Git Policy](contributors/git-policy.html)
+- [Git Cookbook](contributors/git-cookbook.html)
- [Coding Conventions](contributors/coding-conventions.html)
- [Versioning Policy](contributors/versioning-policy.html)