[[git-policy]]
= Git Policy

:Notice: 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.
:page-partial:



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 `main`

* 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:

* http://git-scm.com/book[Pro Git] book (free in electronic form)
* https://github.s3.amazonaws.com/media/book.pdf[Git community book]
* http://git-scm.com/2011/07/11/reset.html[git reset demystified] - differentiating the working directory vs index/staging area

And, of course, there is loads of good advice on http://stackoverflow.com/questions/tagged/git[stackoverflow.com]

== Workflow

There are many ways of using Git, but the Apache Causeway committers have adopted the following workflow:

* create a topic branch for a feature +
+
[source,bash]
----
git checkout -b CAUSEWAY-999
----

* periodically, push the branch to origin (for safekeeping): +
+
[source,bash]
----
git push origin CAUSEWAY-999
----

* `rebase` the topic branch periodically on `main`.
+
How often you do this will depend on whether you are collaborating with others on the feature.
You need to ensure that your co-worker has no outstanding work before you do this; otherwise it'll create merge conflict hell for them:
+
[source,bash]
----
git checkout main
git pull
git checkout CAUSEWAY-999
git rebase main
git push origin CAUSEWAY-999 --force
----

* when feature is complete, rebase once more (as above), then switch to `main` and perform a `merge --no-ff`: +
+
[source,bash]
----
git checkout main
git merge --no-ff CAUSEWAY-999
----

* finally, remove the branch +
+
[source,bash]
----
git branch -d CAUSEWAY-999
git push origin --delete CAUSEWAY-999
----

This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to `main` to see the ultimate impact of the changes (acting a bit like a summary).

== Commit message

The minimum we expect in a commit messages is:

[source,bash]
----
CAUSEWAY-nnn: brief summary here

- optionally, longer details
- should be written here
- in bullet points
----

where `CAUSEWAY-nnn` is a ticket raised in our https://issues.apache.org/jira/browse/CAUSEWAY[JIRA issue tracker].

For non-committers we typically expect more detail again; see the xref:conguide:ROOT:contributing.adoc[contributing] page for the longer format recommended for contributors to use.
