From 8fcddc707676becbf90aced074f44f32b17eb852 Mon Sep 17 00:00:00 2001
From: Andrei Pozolotin <Andrei.Pozolotin@gmail.com>
Date: Mon, 20 Aug 2012 20:28:51 -0500
Subject: [PATCH] github contributions

---
 manual/src/main/webapp/_navigation.conf            |    3 +-
 .../developers-guide/github-contributions.conf     |   75 ++++++++++++++++++++
 manual/src/main/webapp/developers-guide/index.conf |    1 +
 3 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 manual/src/main/webapp/developers-guide/github-contributions.conf

diff --git a/manual/src/main/webapp/_navigation.conf b/manual/src/main/webapp/_navigation.conf
index 6bed05a..e1ffeed 100644
--- a/manual/src/main/webapp/_navigation.conf
+++ b/manual/src/main/webapp/_navigation.conf
@@ -40,6 +40,7 @@ h3. [Developers Guide|/developers-guide/index]
 - [Using the Karaf Maven plugin|/developers-guide/karaf-maven-plugin]
 - [Security Framework|/developers-guide/security-framework]
 - [Writing Integration Test|/developers-guide/writing-tests]
-- {Custom Distribution|/developers-guide/custom-distribution]
+- [Custom Distribution|/developers-guide/custom-distribution]
+- [Github Contributions|/developers-guide/github-contributions]
 
 h3. [Commands|/commands/commands]
diff --git a/manual/src/main/webapp/developers-guide/github-contributions.conf b/manual/src/main/webapp/developers-guide/github-contributions.conf
new file mode 100644
index 0000000..cca5ecd
--- /dev/null
+++ b/manual/src/main/webapp/developers-guide/github-contributions.conf
@@ -0,0 +1,75 @@
+h1. Github Contributions
+
+Some people prefer to make contributions to karaf source via github.
+If you are one of them, this is for you. :-)
+
+
+h2. Introduction
+
+Apache Karaf is available as a periodically replicated mirror on: [https://github.com/apache/karaf] 
+
+
+h2. Suggested Workflow
+
+# make a fork of karaf repo github mirror
+# do all your new work on your own karaf fork
+# when ready, file a jira issue [https://issues.apache.org/jira/browse/KARAF], attach the link to your github pull request, and ask for a review
+# one of karaf committers will discuss your pull request on github; and at some point your pull request will be accepted 
+# when your pull request is accepted, squash it into a single commit and attach single patch file to the original jira, with ASF grant check box selected  
+# now pray to your favorite ASF committer to really accept the patch :-)
+# when your patch is committed to the svn, and you can verify it in the latest karaf snapshot, close your pull request on github 
+
+
+h2. License Reminder
+
+in order for your contributions to be accepted:
+
+* all files must contain ASL license grant header
+
+* you must select ASF grant check box when attaching patch to the jira
+
+
+h2. How to Generate a One-File-Patch Via Throw-Away Branch
+
+here is one way to generate squash of your commits:
+
+[http://stackoverflow.com/questions/616556/how-do-you-squash-commits-into-one-patch-with-git-format-patch]
+
+{code}
+
+#
+# 'archon' referers to karaf mirror
+# 'origin' referers to your own fork
+#
+
+# attach karaf mirror as remote, if not done yet
+git remote add archon https://github.com/apache/karaf
+
+# fetch latest karaf mirror
+git fetch archon 
+
+# ensure you are on your fork trunk
+git checkout origin/trunk
+
+# kill previous patch delivery, if you had one
+git branch -D delivery
+
+# make new delivery throw-away branch, based on latest karaf mirror
+git branch delivery archon/trunk
+
+# use it
+git checkout delivery
+
+# squash all your local development into a single commit
+git merge --squash trunk
+
+# commit it to the delivery branch
+git commit -m "delivery"
+
+# generate a patch file against the mirror
+git format-patch archon/trunk
+
+{code}
+
+root of your karaf source now contains a file named "0001-delivery.patch"
+which you should attach to your karaf jira, and ask to commit to the svn trunk
diff --git a/manual/src/main/webapp/developers-guide/index.conf b/manual/src/main/webapp/developers-guide/index.conf
index a6be7a2..c7724a1 100644
--- a/manual/src/main/webapp/developers-guide/index.conf
+++ b/manual/src/main/webapp/developers-guide/index.conf
@@ -13,3 +13,4 @@ h1. Developers Guide
 * [Writing integration tests|writing-tests]
 * [Creating bundles|creating-bundles]
 * [Shell syntax|shell-syntax]
+* [Github Contributions|github-contributions]
-- 
1.7.9.5