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 2016/01/04 16:23:03 UTC
[8/9] isis git commit: ISIS-1287: splitting out contributors vs
committers guides
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc
deleted file mode 100644
index 80b3e93..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc
+++ /dev/null
@@ -1,571 +0,0 @@
-[[_cg_committers_key-generation]]
-= Key Generation
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-
-In order that a contributor can make a release it is necessary for them to have generated a key and had that key recognized by other members of the Apache Software Foundation.
-
-For further background information on this topic, see the http://www.apache.org/dev/release-signing.html[release signing page] and the http://www.apache.org/dev/openpgp.html#generate-key[openpgp page] on the Apache wiki.
-
-
-
-== Install and Configure gpg
-
-Download and install GnuPG (gpg), version 1.4.10 or higher.
-
-Then, edit `~/.gnupg/gpg.conf` (on Windows, the file to edit is `C:\Users\xxx\AppData\Roaming\gnupg\gpg.conf`) so that the default is to generate a strong key:
-
-[source,bash]
-----
-personal-digest-preferences SHA512
-cert-digest-algo SHA512
-default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
-----
-
-
-
-
-== Key Generation
-
-The Apache Software Foundation requires that keys are signed with a key (or subkey) based on RSA 4096 bits. To do this:
-
-[source]
-----
-$ gpg --gen-key
-gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Please select what kind of key you want:
- (1) RSA and RSA (default)
- (2) DSA and Elgamal
- (3) DSA (sign only)
- (4) RSA (sign only)
-Your selection?
-----
-
-Specify RSA key:
-
-[source]
-----
-Your selection? 1
-
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048)
-----
-
-Specify key length as 4096 bits:
-
-[source]
-----
-What keysize do you want? (2048) 4096
-Requested keysize is 4096 bits
-
-Please specify how long the key should be valid.
- 0 = key does not expire
- <n> = key expires in n days
- <n>w = key expires in n weeks
- <n>m = key expires in n months
- <n>y = key expires in n years
-Key is valid for? (0)
-----
-
-Specify key as non-expiring:
-
-[source]
-----
-Key is valid for? (0) 0
-Key does not expire at all
-Is this correct? (y/N) y
-
-You need a user ID to identify your key; the software constructs the user ID
-from the Real Name, Comment and Email Address in this form:
- "Heinrich Heine (Der Dichter) <he...@duesseldorf.de>"
-
-Real name:
-----
-
-Enter your name, email and comment:
-
-* use your apache.org email
-* the comment should be "CODE SIGNING KEY"
-
-Real name: Xxx Xxxxxxxxx
-Email address: link:mailto:xxx@apache.org[xxx@apache.org]
-Comment: CODE SIGNING KEY
-You selected this USER-ID:
- "Xxx Xxxxxxxxx (CODE SIGNING KEY) link:mailto:xxx@apache.org[xxx@apache.org]"
-
-Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
-
-You need a Passphrase to protect your secret key.
-Enter passphrase:
-
-Provide a passphrase to secure your key.
-
-[source]
-----
-Enter passphrase:
-Repeat passphrase:
-----
-
-GPG will goes on to generate your key:
-
-[source]
-----
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.........................+++++
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-....+++++
-...+++++
-gpg: key nnnnnnnn marked as ultimately trusted
-public and secret key created and signed.
-
-gpg: checking the trustdb
-gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
-gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
-pub 4096R/nnnnnnnn yyyy-mm-dd
- Key fingerprint = xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
-uid Xxx Xxxxxx <xx...@apache.org>
-sub 4096R/kkkkkkkk yyyy-mm-dd
-----
-
-The public key with id nnnnnnnn should now be stored in `~/.gnupg/pubring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/pubring.pgp`).
-
-To confirm the key has been generated, use:
-
-[source]
-----
-$ gpg --list-keys --fingerprint
-----
-
-The key Id is the one true way to identify the key, and is also the last 8 digits of the fingerprint. The corresponding secret key for id `nnnnnnnn` is stored in `~/.gnupg/secring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/secring.pgp`).
-
-It's also worth confirming the key has the correct preference of algorithms (reflecting the initial configuration we did earlier). For this, enter the gpg shell for your new key:
-
-[source]
-----
-$ gpg --edit-key nnnnnnnnn
->gpg
-----
-
-where `nnnnnnnn` is your key id. Now, use the 'showpref' subcommand to list details:
-
-[source]
-----
-gpg> showpref
-[ultimate] (1). Xxx Xxxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
- Cipher: AES256, AES192, AES, CAST5, 3DES
- Digest: SHA512, SHA384, SHA256, SHA224, SHA1
- Compression: ZLIB, BZIP2, ZIP, Uncompressed
- Features: MDC, Keyserver no-modify
-
-gpg>
-----
-
-The Digest line should list SHA-512 first and SHA-1 last. If it doesn't, use the "setpref" command:
-
-[source]
-----
-setpref SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
-----
-
-Finally, remember to take a backup of your key and the keyring (ie, backup the `.gnupg` directory and its contents).
-
-== Subkey Generation
-
-It's recommended to use a subkey with an expiry date to sign releases, rather than your main, non-expiring key. If a subkey is present, then gpg will use it for signing in preference to the main key.
-
-[NOTE]
-====
-After (binary) release artifacts are created, they are deployed to the ASF's Nexus staging repository. However, Nexus seems unable to retrieve a subkey from the public key server. Until we find a fix/workaround for this, all releases should be signed just with a regular non-expiring main key.
-====
-
-
-
-To create a subkey Enter the gpg shell using (the identifier of) your main key:
-
-[source]
-----
-gpg --edit-key xxxxxxxx
-gpg>
-----
-
-Type 'addkey' to create a subkey, and enter your passphrase for the main key:
-
-[source]
-----
-gpg> addkey
-Key is protected.
-[enter your secret passphrase]
-
-You need a passphrase to unlock the secret key for
-user: "Dan Haywood (CODE SIGNING KEY) <da...@apache.org>"
-4096-bit RSA key, ID xxxxxxxx, created 2011-02-01
-
-Please select what kind of key you want:
- (3) DSA (sign only)
- (4) RSA (sign only)
- (5) Elgamal (encrypt only)
- (6) RSA (encrypt only)
-Your selection?
-----
-
-Select (6) to choose an RSA key for encryption:
-
-[NOTE]
-====
-It would seem that Nexus repository manager does not recognize RSA subkeys with an 'S'ign usage; see this discussion on a mailing list and this issue on Sonatype's JIRA
-====
-
-
-[source]
-----
-Your selection? 6
-
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048) 4096
-
-Requested keysize is 4096 bits
-
-Please specify how long the key should be valid.
- 0 = key does not expire
- <n> = key expires in n days
- <n>w = key expires in n weeks
- <n>m = key expires in n months
- <n>y = key expires in n years
-Key is valid for?
-----
-
-Specify that the key is valid for 1 year:
-
-[source]
-----
-Key is valid for? (0) 1y
-
-Key expires at yy/MM/dd hh:mm:ss
-Is this correct? (y/N) y
-Really create? (y/N) y
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.+++++
-
-pub 4096R/xxxxxxxx created: yyyy-mm-dd expires: never usage: SC
- trust: ultimate validity: ultimate
-sub 4096R/xxxxxxxx created: yyyy-mm-dd expires: yyYY-mm-dd usage: E
-[ultimate] (1). Dan Haywood (CODE SIGNING KEY) <da...@apache.org>
-
-gpg>
-----
-
-Quit the gpg shell; you now have a subkey.
-
-== Generate a Revocation Certificate
-
-It's good practice to generate a number of revocation certificates so that the key can be revoked if it happens to be compromised. See the http://www.apache.org/dev/openpgp.html#revocation-certs[gpg page] on the Apache wiki for more background on this topic.
-
-First, generate a "no reason specified" key:
-
-[source]
-----
-$ gpg --output revoke-nnnnnnnn-0.asc --armor --gen-revoke nnnnnnnn
-
-sec 4096R/nnnnnnnn yyyy-mm-dd Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
-Create a revocation certificate for this key? (y/N) Y
-
-Please select the reason for the revocation:
- 0 = No reason specified
- 1 = Key has been compromised
- 2 = Key is superseded
- 3 = Key is no longer used
- Q = Cancel
-(Probably you want to select 1 here)
-Your decision?
-----
-
-Select 0.
-
-[source]
-----
-Your decision? 0
-
-Enter an optional description; end it with an empty line:
-----
-
-Provide a description:
-
-[source]
-----
-> Generic certificate to revoke key, generated at time of key creation.
->
-Reason for revocation: No reason specified
-Generic certificate to revoke key, generated at time of key creation.
-Is this okay? (y/N)
-----
-
-Confirm this is ok.
-
-[source]
-----
-Is this okay? y
-
-You need a passphrase to unlock the secret key for
-user: "Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>"
-4096-bit RSA key, ID nnnnnnnn, created yyyy-mm-dd
-
-Enter passphrase:
-</pre>
-
-Enter a passphrase:
-
-<pre>
-Enter passphrase:
-Revocation certificate created.
-
-Please move it to a medium which you can hide away; if Mallory gets
-access to this certificate he can use it to make your key unusable.
-It is smart to print this certificate and store it away, just in case
-your media become unreadable. But have some caution: The print system of
-your machine might store the data and make it available to others!
-----
-
-The file `revoke-nnnnnnnn-0.asc` should be created: Then, backup this file.
-
-Now repeat the process to create two further revocation certificates:
-
-[source,bash]
-----
-gpg --output revoke-nnnnnnnn-1.asc --armor --gen-revoke nnnnnnnn
-----
-
-Specify reason as "1 = Key has been compromised"
-
-and:
-
-[source,bash]
-----
-gpg --output revoke-nnnnnnnn-3.asc --armor --gen-revoke nnnnnnnn
-----
-
-Specify reason as "3 = Key is no longer used"
-
-Backup these files also.
-
-
-
-
-
-== Publish Key
-
-It is also necessary to publish your key. There are several places where this should be done. In most cases, you'll need the "armored" " (ie ASCII) representation of your key. This can be generated using:
-
-[source]
-----
-$ gpg --armor --export nnnnnnnn > nnnnnnnn.asc
-----
-
-where `nnnnnnnn` is the id of your public key.
-
-You'll also need the fingerprint of your key. This can be generated using:
-
-[source]
-----
-$ gpg --fingerprint nnnnnnnn
-----
-
-The output from this command includes a line beginning "Key fingerprint", followed by a (space delimited) 40 character hexadecimal fingerprint. The last 8 characters should be the same as the key id (`nnnnnnnn`).
-
-=== Publish to a public key server
-
-To a publish your key to a public key server (eg the MIT key server hosted at http://pgp.mit.edu[http://pgp.mit.edu]), use the procedure below. Public key servers synchronize with each other, so publishing to one key server should be sufficient. For background reading on this, see the http://www.apache.org/dev/release-signing.html#keyserver-upload[release signing page] on the Apache wiki, and the http://maven.apache.org/developers/release/pmc-gpg-keys.html[gpg key page] on the Maven wiki.
-
-To send the key up to the key server:
-
-[source]
-----
-$ gpg --send-keys --keyserver pgp.mit.edu nnnnnnnn
-----
-
-where `nnnnnnnn` is the key Id.
-
-Alternatively, you can browse to the http://pgp.mit.edu/[MIT key server] and paste in the armored representation of your key.
-
-Confirm the key has been added by browsing to submitting the following URL:
-
-`http://pgp.mit.edu:11371/pks/lookup?search=0xnnnnnnnnn&op=vindex`
-
-again, where `nnnnnnnn` is the key Id.
-
-=== Publish to your Apache home directory
-
-The armored representation of your public key should be uploaded to your home directory on `people.apache.org`, and renamed as `.pgpkey`. Make sure this is readable by all.
-
-=== Publish to your Apache HTML home directory
-
-The armored representation of your public key should be uploaded to your `public_html` home directory on `people.apache.org`, named `nnnnnnnn.asc`. Make sure this is readable by all.
-
-Check the file is accessible by browsing to:
-
-`http://people.apache.org/~xxxxxxxx/nnnnnnnn.asc`
-
-where
-
-* `xxxxxxxx` is your apache LDAP user name
-* `nnnnnnnn` is your public key id.
-
-=== FOAF
-
-First, check out the committers/info directory:
-
-Go to Apache http://people.apache.org/foaf/foafamatic.html[FOAF-a-matic] web page to generate the FOAF file text (we copy this text out in a minute):
-
-* enter ASF LDAP user name
-* enter First name, Last name
-* for PGP key fingerprints, add Key
-* paste in the key id
-* paste in the fingerprint
-* press "Create"
-
-In the box below, you should have a FOAF file, something like:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<rdf:RDF
- xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
- xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
- xmlns:foaf="http://xmlns.com/foaf/0.1/"
- xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
- xmlns:pm="http://www.web-semantics.org/ns/pm#"
- xmlns:wot="http://xmlns.com/wot/0.1/"
- xmlns:rss="http://purl.org/rss/1.0/"
- xmlns:dc="http://purl.org/dc/elements/1.1/"
- xmlns:ical="http://www.w3.org/2002/12/cal/ical#"
- xmlns:doap="http://usefulinc.com/ns/doap#">
- <foaf:Person rdf:ID="danhaywood">
- <foaf:name>Xxx Xxxxxxxx</foaf:name>
- <foaf:givenname>Xxx</foaf:givenname>
- <foaf:family_name>Xxxxxxxx</foaf:family_name>
- <wot:hasKey>
- <wot:PubKey>
- <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
- <wot:hex_id>nnnnnnnn</wot:hex_id>
- </wot:PubKey>
- </wot:hasKey>
- </foaf:Person>
-</rdf:RDF>
-----
-
-(If you are creating the FOAF file for the first time, you may want to add additional details).
-
-From this, copy out the `wot:key`, and paste into your FDF file in `committers/info`:
-
-[source,xml]
-----
-<wot:hasKey>
- <wot:PubKey>
- <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
- <wot:hex_id>nnnnnnnn</wot:hex_id>
- </wot:PubKey>
-</wot:hasKey>
-----
-
-Then, manually add in a `<wot:pubkeyAddress>` element within `<wot:PubKey>`:
-
-[source,xml]
-----
-<wot:hasKey>
- <wot:PubKey>
- <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
- <wot:hex_id>nnnnnnnn</wot:hex_id>
- <wot:pubkeyAddress rdf:resource="http://people.apache.org/~username/nnnnnnnn.asc/">
- </wot:PubKey>
-</wot:hasKey>
-----
-
-ie, referencing your publically exported public key
-
-Finally, commit your changes.
-
-=== Save to `KEYS`
-
-The armored representation of the public key should be saved to Apache Isis' `KEYS` file, http://www.apache.org/dist/isis/KEYS[http://www.apache.org/dist/isis/KEYS] (that is, in the ASF distribution directory for Apache Isis).
-
-First, in a new directory, checkout this file:
-
-[source]
-----
-svn -N co https://svn.apache.org/repos/asf/isis/ .
-----
-
-This should bring down the `KEYS` file.
-
-Then, export your signature and armored representation.
-
-[source]
-----
-gpg --list-sigs nnnnnnnn >>KEYS
-gpg --armor --export nnnnnnnn >>KEYS
-----
-
-Then commit.
-
-=== id.apache.org
-
-Log onto `id.apache.org` and ensure that the finger print of your public key is correct.
-
-== Attend Key Signing Party (Apache web of trust)
-
-It is strongly advised that the contributor attend a key signing party at an Apache event, in order that other Apache committers/members can in person verify their identity against the key. The process for this is described http://www.apache.org/dev/release-signing.html#key-signing-party[here] and http://wiki.apache.org/apachecon/PgpKeySigning[here].
-
-== Update Maven Settings file (`~/.m2/settings.xml`)
-
-The Maven release plugin will automatically sign the release, however it is necessary to update the `~/.m2/settings.xml` file with your GPG acronym passphrase in order that it can use your secret key. This is defined under a profile so that it is activated only when we perform a release (as defined by `[org,apache:apache]` parent POM.
-
-Therefore, make the following edits:
-
-[source,xml]
-----
-<settings>
- ...
- <profiles>
- <profile>
- <id>apache-release</id>
- <properties>
- <gpg.passphrase>xxx xxx xxx xxx xxx xxx xxx</gpg.passphrase>
- </properties>
- </profile>
- </profiles>
-</settings>
-----
-
-In addition, to allow the release plugin to tag SVN changes, you must either add in your LDAP username/password or configure `.ssh`:
-
-[source,xml]
-----
-<settings>
- ...
- <servers>
- ...
- <server>
- <id>apache.releases.https</id>
- <username>xxxx</username>
- <password>xxxx</password>
- </server>
- </servers>
-</settings>
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_merging-a-pull-request.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_merging-a-pull-request.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_merging-a-pull-request.adoc
deleted file mode 100644
index e4107ea..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_merging-a-pull-request.adoc
+++ /dev/null
@@ -1,123 +0,0 @@
-[[_cg_committers_merging-a-pull-request]]
-= Merging a Pull Request
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-The process for merging in github pull requests (so that they can be tested locally before committing) has been scripted in the `github-pr.sh` script.
-
-The script will merge the fork into a temporary branch, and then run a build. Once you are happy, you can commit.
-
-The script requires `jq` to parse JSON; see the section below on installing pre-requisites.
-
-
-
-== Process and Usage
-
-The overall process is as follows:
-
-* locate/raise corresponding JIRA ticket, eg ISIS-1162
-* checkout branch from which PR was forked (usually just 'master')
-* merge PR into temporary branch using the `github-pr.sh` script
-* test the change locally (run the app, rebuild, manual regression tests etc)
-* if required, tidy up/refactor code as required
-* merge temporary branch into mainline, and commit
-
-
-For example:
-
-[source,bash]
-----
-github-pr.sh isis 1162 31
-----
-
-where:
-
-* `isis` is the JIRA project and repo
-* `1162` is the JIRA ticket number
-* `31` is the gthub PR issue number
-
-
-
-
-== Example transcript
-
-The listing below shows the steps taken by the script:
-
-[source,bash]
-----
-$ sh github-pr.sh isis 1162 31
-
-Found JIRA ticket
-Found github PR
-branch_name_local: master
-username : sebadiaz
-repo_full_name : sebadiaz/isis
-repo_clone_url : https://github.com/sebadiaz/isis.git
-branch_name_fork : master
-
-merging into: ISIS-1162_pr-31
-
-Deleting branch 'ISIS-1162_pr-31'
-Deleted branch ISIS-1162_pr-31 (was bd2e3c2).
-Creating the branch ISIS-1162_pr-31
-Switched to a new branch 'ISIS-1162_pr-31'
-Pulling the changes from https://github.com/sebadiaz/isis.git master
-From https://github.com/sebadiaz/isis
- * branch master -> FETCH_HEAD
-Auto-merging core/pom.xml
-Merge made by the 'recursive' strategy.
- core/pom.xml | 3 +-
- .../apache/isis/security/shiro/IsisLdapRealm.java | 198 +++++++++++++++++++--
- 2 files changed, 186 insertions(+), 15 deletions(-)
-
-Merged the PR; hit enter to build
-----
-
-The build now commences. Once done, the script continues:
-
-[source,bash]
-----
-If build successful and happy to merge, execute:
-
-git checkout master && git merge --no-ff ISIS-1162_pr-31 && git branch -d ISIS-1162_pr-31
-----
-
-The screenshot belows shows the history we end up with:
-
-image::{_imagesdir}committers/github-pr-history.png[link="{_imagesdir}committers/github-pr-history.png"]
-
-This shows the fork being merged into the temporary branch ("ISIS-1162_pr-31"), then some further tidy-up, and finally the merging of the temporary branch into mainline.
-
-Note that there is no rebasing in this model. This is intentional: when the merged branch is pushed, github will automatically close the original pull request.
-
-
-
-
-== Prerequisites
-
-The script uses 'jq' to parse JSON. To install:
-
-* on Linux: +
-+
-[source,bash]
-----
-aptitude install jq
-----
-
-* on MacOS: +
-+
-[source,bash]
-----
-brew install jq
-----
-
-* on Windows: +
-+
-Download exe from http://stedolan.github.io/jq/download/[website]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc
deleted file mode 100644
index f6b4b91..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc
+++ /dev/null
@@ -1,71 +0,0 @@
-[[_cg_committers_pmc-notes]]
-= Appendix: PMC
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-Every ASF project has a Project Management Committee, or PMC. This committee is ultimately responsible for the long-term management of the framework. More information about PMCs can be found link:http://www.apache.org/dev/pmc.html[here]
-
-In Apache Isis, every committer is a member of the PMC.
-
-This page contains some general notes on maintenance activities required by PMC members.
-
-
-
-== Accessing `people.apache.org`
-
-Must be accessed via ssh.
-
-eg:
-
-[source,bash]
-----
-ssh danhaywood@people.apache.org
-----
-
-and when prompted, provide passphrase for private key... though I've forgotten what I did to set this up in the first place, though :-(
-
-
-
-
-== LDAP Access (UNIX groups)
-
-Whenever we get a new committer, the ASF LDAP entries must be maintained to grant access to our repos and various other 'karma'.
-
-Log onto `people.apache.org`, then use:
-
-[source]
-----
-list_unix_group.pl isis
-----
-
-to list committers
-
-[source]
-----
-list_committee.pl isis
-----
-
-to list the PMC committee members (in Apache Isis, every committer should be on the PMC committee)
-
-To change membership of either the committers or the PMC, use:
-
-[source]
-----
-modify_unix_group.pl isis --add joebloggs
-modify_unix_group.pl isis --remove joebloggs
-----
-
-and
-
-[source]
-----
-modify_committee.pl gump --add joebloggs
-modify_committee.pl gump --remove joebloggs
-----
-
-respectively.
-
-Further details are in http://www.apache.org/dev/pmc.html#SVNaccess[these ASF docs]. (They talk about SVN access, but really it is LDAP access).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-successful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-successful.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-successful.adoc
deleted file mode 100644
index 9b7cc3b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-successful.adoc
+++ /dev/null
@@ -1,428 +0,0 @@
-[[_cg_committers_post-release-successful]]
-= Post Release (Successful)
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-The release process consists of:
-
-* the release manager xref:cg.adoc#_cg_committers_cutting-a-release[cutting the release]
-* members of the Apache Isis PMC xref:cg.adoc#_cg_committers_verifying-releases[verifying] and voting on the release
-* the release manager performing post-release tasks, for either a successful or an xref:cg.adoc#_cg_committers_post-release-unsuccessful[unsuccessful] vote (former documented below)
-
-For a vote to succeed, there must be +3 votes from PMC members, and the vote must have been open at least 72 hours. If there are not +3 votes after this time then it is perfectly permissible to keep the vote open longer.
-
-This section describes the steps to perform if the vote has been successful.
-
-
-
-
-== Inform dev ML
-
-Post the results to the `dev@isis.a.o` mailing list:
-
-[source,bash]
-----
-[RESULT] [VOTE] Apache Isis Core release 1.12.0
-----
-
-using the body (alter last line as appropriate):
-
-[source,bash]
-----
-The vote has completed with the following result :
-
- +1 (binding): <i>list of names</i>
- +1 (non binding): <i>list of names</i>
-
- -1 (binding): <i>list of names</i>
- -1 (non binding): <i>list of names</i>
-
-The vote is SUCCESSFUL.
-----
-
-
-
-== Update tags
-
-Replace the `-RCn` tag with another without the qualifier.
-
-You can do this using the `scripts/promoterctag.sh` script; for example:
-
-[source,bash]
-----
-sh scripts/promoterctag.sh isis-1.12.0 RC1
-sh scripts/promoterctag.sh simpleapp-archetype-1.12.0 RC1
-----
-
-
-Then, continue onto the next section for the steps to promote and announce the release.
-
-
-
-
-== Release to Maven Central
-
-From the http://repository.apache.org[ASF Nexus repository], select the staging repository and select 'release' from the top menu.
-
-
-image::{_imagesdir}release-process/nexus-release-1.png[width="600px",link="{_imagesdir}release-process/nexus-release-1.png"]
-
-This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.
-
-
-
-
-== Release Source Zip
-
-As described in the link:http://www.apache.org/dev/release-publishing.html#distribution_dist[Apache documentation], each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at link:https://dist.apache.org/repos/dist[https://dist.apache.org/repos/dist]. Once a release vote passes, the release manager should `svn add` the artifacts (plus signature and hash files) into this location. The release is then automatically pushed to http://www.apache.org/dist/[http://www.apache.org/dist/] by `svnpubsub`. Only the most recent release of each supported release line should be contained here, old versions should be deleted.
-
-Each project is responsible for the structure of its directory. The directory structure of Apache Isis reflects the directory structure in our git source code repo:
-
-[source]
-----
-isis/
- core/
- example/
- archetype/
- simpleapp/
-----
-
-If necessary, checkout this directory structure:
-
-[source,bash]
-----
-svn co https://dist.apache.org/repos/dist/release/isis isis-dist
-----
-
-Next, add the new release into the appropriate directory, and delete any previous release. The `upd.sh` script can be used to automate this:
-
-[source,bash]
-----
-old_ver=$1
-new_ver=$2
-
-
-# constants
-repo_root=https://repository.apache.org/content/repositories/releases/org/apache/isis
-
-zip="source-release.zip"
-asc="$zip.asc"
-md5="$zip.md5"
-
-
-#
-# isis-core
-#
-type="core"
-fullname="isis"
-pushd isis-core
-
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$asc
-svn add $fullname-$new_ver-$asc
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$md5
-svn add $fullname-$new_ver-$md5
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$zip
-svn add $fullname-$new_ver-$zip
-
-svn delete $fullname-$old_ver-$asc
-svn delete $fullname-$old_ver-$md5
-svn delete $fullname-$old_ver-$zip
-
-popd
-
-
-#
-# simpleapp-archetype
-#
-type="archetype"
-fullname="simpleapp-archetype"
-pushd $type/$fullname
-
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$md5
-svn add $fullname-$new_ver-$md5
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$asc
-svn add $fullname-$new_ver-$asc
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$zip
-svn add $fullname-$new_ver-$zip
-
-svn delete $fullname-$old_ver-$md5
-svn delete $fullname-$old_ver-$asc
-svn delete $fullname-$old_ver-$zip
-
-popd
-----
-
-For example:
-
-[source,bash]
-----
-sh upd.sh 1.11.0 1.12.0
-----
-
-The script downloads the artefacts from the Nexus release repository, adds the artefacts to subsversion and deletes the previous version.
-
-At the end, commit the changes:
-
-[source]
-----
-svn commit -m "publishing isis source releases to dist.apache.org"
-----
-
-
-
-
-== Update JIRA
-
-=== Generate Release Notes
-
-From the root directory, generate the release notes for the current release, in Asciidoc format; eg:
-
-[source,bash]
-----
-sh scripts/jira-release-notes.sh ISIS 1.12.0 > /tmp/1
-----
-
-
-=== Close tickets
-
-Close all JIRA tickets for the release, or moved to future releases if not yet addressed. Any tickets that were partially implemented should be closed, and new tickets created for the functionality on the ticket not yet implemented.
-
-
-
-=== Mark the version as released
-
-In JIRA, go to the link:https://issues.apache.org/jira/plugins/servlet/project-config/ISIS/versions[administration section] for the Apache Isis project and update the version as being released.
-
-In the link:https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=87[Kanban view] this will have the effect of marking all tickets as released (clearing the "done" column).
-
-
-=== Create new JIRA
-
-Create a new JIRA ticket as a catch-all for the _next_ release.
-
-
-=== Update the ASF Reporter website
-
-Log the new release in the link:https://reporter.apache.org/addrelease.html?isis[ASF Reporter website].
-
-
-
-== Update website
-
-Update the Apache Isis (asciidoc) website:
-
-* Paste in the JIRA-generated release notes generated above, adding to top of `adocs/documentation/src/main/asciidoc/release-notes.adoc`. Also add a summary line for the release.
-
-* Search for any `-SNAPSHOT` suffices, and remove
-
-* Search these release procedures, and update any hard-coded reference to the release to the next release (so when they are followed next time the text will be correct).
-
-* Update the link:../downloads.html[downloads page] with a link to the source release zip file (under https://dist.apache.org/repos/dist/release/isis[https://dist.apache.org/repos/dist/release/isis])
-
-* Update any pages (`.adoc`, `.md`, `.html` etc) that describe how to run the archetype, and ensure they reference the correct version. +
-+
-A search for `archetypeGroupId=org.apache.isis.archetype` should find these pages.
-
-* update the link:../doap_isis.rdf[DOAP RDF] file (which provides a machine-parseable description of the project) should also be updated with details of the new release. Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service. +
-+
-For more information on DOAP files, see these http://projects.apache.org/doap.html[Apache policy docs].
-
-* Update the https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=blob_plain;f=STATUS;hb=HEAD[STATUS] file (in root of Apache Isis' source) should be updated with details of the new release.
-
-
-Don't forget to commit the `.adoc` changes and publish to the isis-site repo.
-
-
-
-
-
-== Announce the release
-
-Announce the release to link:mailto:users@isis.apache.org[users mailing list].
-
-For example, for a release of Apache Isis Core, use the following subject:
-
-[source,bash]
-----
-[ANN] Apache Isis version 1.12.0 Released
-----
-
-And use the following body (summarizing the main points as required):
-
-[source]
-----
-The Apache Isis team is pleased to announce the release of Apache Isis v1.12.0.
-
-New features in this release include:
-* ...
-
-Full release notes are available on the Apache Isis website at [1]. Please also read the migration notes [2].
-
-You can access this release directly from the Maven central repo [3], or download the release and build it from
-source [4].
-
-Enjoy!
-
---The Apache Isis team
-
-[1] http://isis.apache.org/release-notes.html#r1.12.0
-[2] http://isis.apache.org/migration-notes.html#_migration-notes_1.11.0-to-1.12.0
-[3] http://search.maven.org
-[4] http://isis.apache.org/downloads.html
-----
-
-
-
-
-== Blog post
-
-link:https://blogs.apache.org/roller-ui/login.rol[Log onto] the http://blogs.apache.org/isis/[Apache blog] and create a new post. Copy-n-paste the above mailing list announcement should suffice.
-
-
-
-
-
-== Merge in release branch
-
-Because we release from a branch, the changes made in the branch (changes to `pom.xml` made by the `maven-release-plugin`, or any manual edits) should be merged back from the release branch back into the `master` branch:
-
-[source,bash]
-----
-git checkout master # update master with latest
-git pull
-git merge release-1.12.0-RC1 # merge branch onto master
-git branch -d release-1.12.0-RC1 # branch no longer needed
-git push origin --delete release-1.12.0-RC1 # remote branch no longer needed
-----
-
-
-Finally, update the simpleapp's root `pom.xml` to reference the next SNAPSHOT release (`1.12.0-SNAPSHOT`)
-
-
-
-== Update dependencies
-
-With the release complete, now is a good time to bump versions of dependencies (so that there is a full release cycle to identify any possible issues).
-
-You will probably want to create a new JIRA ticket for these updates (or if minor then use the "catch-all" JIRA ticket raised earlier for the next release).
-
-
-=== Update parent of Core
-
-Check (via link:http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache%22%20a%3A%22apache%22[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 to match the newer version:
-
-[source,xml]
-----
-<parent>
- <groupId>org.apache</groupId>
- <artifactId>apache</artifactId>
- <version>NN</version>
- <relativePath />
-</parent>
-----
-
-where `NN` is the updated version number.
-
-
-
-=== Update plugin versions
-
-The `maven-versions-plugin` should be used to determine if there are newer versions of any of the plugins used to build Apache Isis. Since this goes off to the internet, it may take a minute or two to run:
-
-[source,bash]
-----
-mvn versions:display-plugin-updates > /tmp/foo
-grep "\->" /tmp/foo | /bin/sort -u
-----
-
-Review the generated output and make updates as you see fit. (However, if updating, please check by searching for known issues with newer versions).
-
-
-
-=== 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:
-
-[source,bash]
-----
-mvn versions:display-dependency-updates > /tmp/foo
-grep "\->" /tmp/foo | /bin/sort -u
-----
-
-Update any of the dependencies that are out-of-date. That said, do note that some dependencies may show up with a new dependency, when in fact the dependency is for an old, badly named version. Also, there may be new dependencies that you do not wish to move to, eg release candidates or milestones.
-
-For example, here is a report showing both of these cases:
-
-[source,bash]
-----
-[INFO] asm:asm ..................................... 3.3.1 -> 20041228.180559
-[INFO] commons-httpclient:commons-httpclient .......... 3.1 -> 3.1-jbossorg-1
-[INFO] commons-logging:commons-logging ......... 1.1.1 -> 99.0-does-not-exist
-[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
-[INFO] org.datanucleus:datanucleus-api-jdo ................ 3.1.2 -> 3.2.0-m1
-[INFO] org.datanucleus:datanucleus-core ................... 3.1.2 -> 3.2.0-m1
-[INFO] org.datanucleus:datanucleus-jodatime ............... 3.1.1 -> 3.2.0-m1
-[INFO] org.datanucleus:datanucleus-rdbms .................. 3.1.2 -> 3.2.0-m1
-[INFO] org.easymock:easymock ................................... 2.5.2 -> 3.1
-[INFO] org.jboss.resteasy:resteasy-jaxrs ............. 2.3.1.GA -> 3.0-beta-1
-----
-
-For these artifacts you will need to search http://search.maven.org[Maven central repo] directly yourself to confirm there are no newer dependencies not shown in this list.
-
-
-
-== Code formatting
-
-This is also a good time to make source code has been cleaned up and formatted according to the Apache Isis and ASF conventions. Use link:resources/Apache-code-style-formatting.xml[this] Eclipse template and link:resources/isis.importorder[this] import order.
-
-
-
-== Push changes
-
-Finally, push the changes up to origin:
-
-[source,bash]
-----
-git fetch # check no new commits on origin/master
-git push
-----
-
-
-== Release Isis Addons
-
-Once the Apache Isis release is available, all of the (non-ASF) link:http://isisaddons.org[Isis Addons] should also be released.
-
-Using this https://gist.github.com/danhaywood/ff17946ee05652402cfb[gist] to invoke operations across all (or selected) addons:
-
-* update its dependency on Apache Isis to reference the newly released version: +
-+
-[source,bash]
-----
-sh forsub.sh sh bumpver_isis.sh 1.12.0
-----
-
-* update the README for each repository
-
-** in the "How to Configure/Use" section, the version referenced in the `pom.xml`, and for the -SNAPSHOT
-** the "Change Log" section
-** the "Release to Maven Central" section at the end
-
-* release to mvn central (contains a sanity check before hand that everything compiles): +
-+
-[source,bash]
-----
-sh forsub.sh sh release.sh "1.12.0" "1.13.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
-----
-
-* update its dependency on Apache Isis to reference the next SNAPSHOT version: +
-+
-[source,bash]
-----
-sh forsub.sh sh bumpver_isis.sh "1.13.0-SNAPSHOT"
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-unsuccessful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-unsuccessful.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-unsuccessful.adoc
deleted file mode 100644
index bf10531..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_post-release-unsuccessful.adoc
+++ /dev/null
@@ -1,94 +0,0 @@
-[[_cg_committers_post-release-unsuccessful]]
-= Post Release (Unsuccessful)
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-The release process consists of:
-
-* the release manager xref:cg.adoc#_cg_committers_cutting-a-release[cutting the release]
-* members of the Apache Isis PMC xref:cg.adoc#_cg_committers_verifying-releases[verifying] and voting on the release
-* the release manager performing post-release tasks, for either a xref:cg.adoc#_cg_committers_post-release-successful[successful] or an unsuccessful vote (latter documented below).
-
-If the vote did not succeed (did not achieve +3 votes after 72 hours and/or is unlikely to do so), then the vote should be closed and the following steps performed.
-
-Note that a release manager may also decide to cancel a vote before 72 hours has elapsed (for example if an error is quickly discovered).
-
-
-== Inform dev ML
-
-Post the results to the `dev@isis.a.o` mailing list.
-
-For example, use the following subject for a vote on Apache Isis Core:
-
-[source,bash]
-----
-[RESULT] [VOTE] Apache Isis Core release 1.12.0
-----
-
-using the body (alter last line as appropriate):
-
-[source,bash]
-----
-The vote has completed with the following result :
-
- +1 (binding): _list of names_
- +1 (non binding): _list of names_
-
- -1 (binding): _list of names_
- -1 (non binding): _list of names_
-
-The vote is UNSUCCESSFUL.
-----
-
-
-== Tidy up branches
-
-Tidy up remote branches in the git repo:
-
-* delete the remote branch, for example: +
-+
-[source,bash]
-----
-git push --delete origin release-1.12.0-RC1
-----
-
-
-* delete the remote origin server's tags, for example: +
-+
-[source,bash]
-----
-git push --delete origin isis-1.12.0-RC1
-git push --delete origin simpleapp-archetype-1.12.0-RC1
-----
-
-
-* delete the tags that were created locally, for example: +
-+
-[source,bash]
-----
-git tag -d isis-1.12.0
-git tag -d isis-1.12.0-RC1
-git tag -d simpleapp-archetype-1.12.0
-git tag -d simpleapp-archetype-1.12.0-RC1
-----
-
-
-== Tidy up the Nexus repo
-
-Drop staging repositories:
-
-* drop the staging repository in http://repository.apache.org[Nexus]
-
-
-
-
-== Reset
-
-Finally, rewind the release branch to prior to the previous release candidate, and continue from there.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc
deleted file mode 100644
index d2c68e1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-[[_cg_committers_release-process-for-snapshots]]
-= Snapshot Releases
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-
-
-Apache Isis consists of a number of separately releasable modules; see the main link:release-process.html[release process] documentation for full details. All the non-core components depend on the `core`, and use the `core`'s parent `pom.xml` as their parent pom.
-
-[NOTE]
-====
-Unless otherwise stated, you should assume that the steps described here are performed in the base directory of the module being released.
-====
-
-
-== Prerequisites
-
-Before you start, make sure you've defined the snapshots repo in your local `~/.m2/settings.xml` file:
-
-[source,xml]
-----
-<settings>
- <servers>
- <!-- To publish a snapshot of some part of Maven -->
- <server>
- <id>apache.snapshots.https</id>
- <username>xxxxxxx</username>
- <password>yyyyyyy</password>
- </server>
- ...
- </servers>
- ...
-</settings>
-----
-
-where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env[ASF docs].
-
-{note
-It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, http://bval.apache.org/release-setup.html[here].
-}
-
-
-
-== Sanity Check
-
-Before deploying the snapshot, perform a quick sanity check.
-
-First, delete all Isis artifacts from your local Maven repo:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-----
-
-Next, check that the framework builds ok:
-
-[source,bash]
-----
-cd core
-mvn clean install -o
-----
-
-Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally).
-
-
-
-== Deploy
-
-Deploy the framework using:
-
-[source,bsah]
-----
-cd core
-mvn -D deploy=snapshot deploy
-----
-
-This will deploy all the modules that make up a release.
-
-[TIP]
-====
-Expect this to take about 10 minutes, give or take.
-====
-
-To confirm that they are present, browse to Apache's https://repository.apache.org[Nexus repository manager] and search for "isis".
-
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-prereqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-prereqs.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-prereqs.adoc
deleted file mode 100644
index 664d1e0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-prereqs.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_cg_committers_release-process-prereqs]]
-= Appendix: Release Prereqs
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-
-This section (appendix) describes the prerequisites for the xref:cg.adoc#_cg_committers_release-process[release process].
-
-
-
-== Public/private key
-
-The most important configuration you require is to set up public/private key pair. This is used by the `maven-release-plugin` to sign the code artifacts. See the page on xref:cg.adoc#_cg_committers_key-generation[key generation] for more details.
-
-In order to prepare the release, you'll (need to) have a `~/.gnupg` directory with the relevant files (`gpg.conf`, `pubring.gpg`, `secring.gpg` etc), and have `gpg` on your operating system PATH.
-
-
-[NOTE]
-====
-If on Windows, the equivalent directory is `c:\users\xxx\appdata\roaming\gnupg`. For `gpg`, use either http://cygwin.com[cygwin.com] or http://www.gpg4win.org[gpg4win.org]. Note also that the mSysGit version of `gpg` (as provided by GitHub's bash client) is not compatible with that provided by cygwin; move it to one side and check that `gpg.exe` being used is that from gpg4win.
-
-====
-
-
-
-== Maven `settings.xml`
-
-During the release process the `maven-deploy-plugin` uploads the generated artifacts to a staging repo on the http://repository.apache.org[Apache repository manager]. This requires your Apache LDAP credentials to be specified in your `~/.m2/settings.xml` file:
-
-[source,xml]
-----
-<settings>
- <servers>
- <server>
- <id>apache.releases.https</id>
- <username>xxxxxxx</username>
- <password>yyyyyyy</password>
- </server>
- ...
- </servers>
- ...
-</settings>
-----
-
-where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env[ASF docs].
-
-
-[NOTE]
-====
-It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, http://bval.apache.org/release-setup.html[here].
-====
-
-
-Also, set up keyphrase for `gpg`; this avoids being prompted during release:
-
-[source,xml]
-----
-<profiles>
- <profile>
- <id>gpg</id>
- <properties>
- <gpg.executable>gpg2</gpg.executable>
- <gpg.passphrase>this is not really my passphrase</gpg.passphrase>
- </properties>
- </profile>
- ...
-</profiles>
-
-<activeProfiles>
- <activeProfile>gpg</activeProfile>
- ...
-</activeProfiles>
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
deleted file mode 100644
index 8625a98..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
+++ /dev/null
@@ -1,304 +0,0 @@
-[[_cg_committers_verifying-releases]]
-= Verifying a Release
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-The release process consists of:
-
-* the release manager xref:cg.adoc#_cg_committers_cutting-a-release[cutting the release]
-* members of the Apache Isis PMC verifying and voting on the release (documented below)
-* the release manager performing post-release tasks, for either a xref:cg.adoc#_cg_committers_post-release-successful[successful] or an xref:cg.adoc#_cg_committers_post-release-unsuccessful[unsuccessful] vote.
-
-This section describes some guidance on what a voter (members of the Apache Isis PMC and anyone else who wishes) is expected to do before casting their vote in order to verify a release.
-
-
-
-== Background
-
-Whenever a release manager announces a vote on a release (as per the xref:cg.adoc#_cg_committers_release-process[release process]) on the link:../support.html[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release. Anyone else can also vote, but only members of the Apache Isis PMC's vote are binding.
-
-Per this http://www.apache.org/dev/release.html[ASF documentation], the legal requirements for an ASF release are:
-
-* a source zip file + corresponding signature (signed by the release manager, which is in the ASF web of trust and in our KEYS file)
-* all source files have the Apache license (this is ensured by the running of the rat plugin prior to release; you could run it on the unzipped source)
-* all dependencies are appropriately licensed; see the `DEPENDENCIES` file which is automatically generated from the POMs plus the supplemental-models.xml file
-
-Note that the binaries are _not_ an ASF release, they merely exist on the Maven central repo as a convenience. That said, you might also want to verify the release by pulling the binaries from the Maven staging repository. Details of how to do this are also documented below.
-
-
-
-== Prerequisites
-
-To verify the source ZIP files, you will need to have imported the public keys used for signing Apache Isis releases. These can be downloaded from the root of the Apache Isis source tree.
-
-Since the Apache Isis source is mirrored on github.com, you can just use:
-
-[source,bash]
-----
-curl http://www.apache.org/dist/isis/KEYS > /tmp/KEYS
-gpg --import /tmp/KEYS
-----
-
-
-Also, we will be rebuilding Isis from source. Therefore delete all Isis artifacts from your local Maven repo:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-----
-
-
-== Verifying source artifacts
-
-You can either verify the source artifacts xref:cg.adoc#_cg_committers_verifying-releases_manual-procedure[manuall], or use a script that xref:cg.adoc#__cg_committers_verifying-releases_automated-procedure[automates] the steps.
-
-
-[[_cg_committers_verifying-releases_manual-procedure]]
-=== Manual procedure
-
-The following section describes the steps to perform to manually verify a release.
-
-==== Download the artifacts
-
-Download both the ZIP and .ASC files from the location specified in the voting email. To verify that the signature is correct, use:
-
-[source,bash]
-----
-gpg --verify isis-x.y.z.zip.asc isis-x.y.z.zip
-----
-
-==== Building source artifacts
-
-Assuming the ZIP file verifies, it should be unpacked, and then the artifact built from source.
-
-To build Apache Isis core, first download any dependencies:
-
-[source]
-----
-mvn dependency:go-offline
-----
-
-Check that no Isis artifacts have yet been downloaded, ie there is no `~/.m2/org/repository/org/apache/isis` directory. If there are, it could indicate that the release being verified incorrectly references previous versions of Apache Isis
-
-Assuming all is ok, build using the `-o` offline flag:
-
-[source]
-----
-mvn clean install -o
-----
-
-Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
-
-
-==== Verifying binary artifacts
-
-You can verify the binary releases by configuring your local Maven install to point to the Maven staging repository (or repositories) and then using them, eg to run the link:../intro/getting-started/simpleapp-archetype.html[simpleapp archetype] and running the resultant app.
-
-Configuring your local Maven install amounts to updating the `~/.m2/settings.xml` file:
-
-[source,xml]
-----
-<profiles>
- <profile>
- <id>verify-isis</id>
- <repositories>
- <repository>
- <id>isis-core-staging</id>
- <name>Isis Core Staging</name>
- <releases>
- <enabled>true</enabled>
- <updatePolicy>always</updatePolicy>
- <checksumPolicy>warn</checksumPolicy>
- </releases>
- <url>http://repository.apache.org/content/repositories/orgapacheisis-10xx</url>
- <layout>default</layout>
- </repository>
- ...
- </repositories>
- </profile>
- ...
-</profiles>
-<activeProfiles>
- <activeProfile>verify-isis</activeProfile>
- ...
-</activeProfiles>
-----
-
-where the repository URL is as provided in the VOTE email. If there is more than one repository (as is sometimes the case if multiple components have been released), then repeat the <repository> section for each.
-
-Once the vote has completed, the staging repositories will be removed and so you should deactive the profile (comment out the `<activeProfile>` element). If you forget to deactive the profile, there should be no adverse effects; Maven will just spend unnecessary cycles attempting to hit a non-existent repo.
-
-
-
-
-[[_cg_committers_verifying-releases_automated-procedure]]
-=== Automated procedure
-
-To save some time in verifying an Apache Isis release we've assembled a script to automate the process. The script is tested on Mac OSX and Linux. Windows users can use Cygwin or http://msysgit.github.io/[msysgit].
-
-It's _recommended_ that you start this process in an empty directory:
-
-[source,bash]
-----
-mkdir ~/verify-isis-release
-cd ~/verify-isis-release
-----
-
-
-==== Copy script to local machine
-
-Copy the following script, save to `verify-isis-release.sh`:
-
-
-[source,bash]
-----
-#!/bin/bash
-# Instructions:
-# -Create an empty directory
-# -Put a .txt file in it containing a list of all the urls of the zip files
-# -Run this script
-# TODO: enhance this script so it will stop when something is broken
-_download(){
- for fil in `cat *.txt`
- do
- echo 'Downloading '$fil
- curl -L -O $fil
- curl -L -O $fil.asc
- done
-}
-_verify(){
- for zip in *.zip
- do
- echo 'Verifying '$zip
- gpg --verify $zip.asc $zip
- done
-}
-_unpack(){
- echo 'Unpacking '
- unzip -q '*.zip'
-}
-_build(){
- echo 'Removing Apache Isis from local repo '$module
- rm -rf ~/.m2/repository/org/apache/isis
- COUNTER=0
- for module in ./*/
- do
- COUNTER=$[COUNTER+1]
- if [ $COUNTER -eq 1 ]
- then
- cd $module
- echo 'Building Core '$module
- mvn clean install -o
- cd ..
- else
- cd $module
- echo 'Building Module '$module
- mvn clean install
- cd ..
- fi
- done
-}
-# The work starts here
-_download
-_verify
-_unpack
-_build
-----
-
-Make sure the script is executable:
-
-[source]
-----
-chmod +x verify-isis-release.sh
-----
-
-[NOTE]
-====
-The script could be enhanced in many ways, feel free to contribute improvements!
-====
-
-
-==== Create an input file
-
-The input file is a plain `.txt` file containing all urls to the packages to be verified. Here's a sample of the release of Apache Isis 1.8.0:
-
-[source]
-----
-https://repository.apache.org/content/repositories/orgapacheisis-063/org/apache/isis/core/isis/1.8.0/isis-1.8.0-source-release.zip
-https://repository.apache.org/content/repositories/orgapacheisis-065/org/apache/isis/archetype/simpleapp-archetype/1.8.0/simpleapp-archetype-1.8.0-source-release.zip
-----
-
-The actual list of packages to be verified will be provided through the mailing list.
-
-
-
-==== Execute the script
-
-Execute...
-
-[source,bash]
-----
-./verify-isis-release.sh
-----
-
-\... and get yourself a cup of coffee.
-
-
-
-
-[[_cg_committers_verifying-releases_creadur]]
-== (Optional) Creadur Tools
-
-The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards.
-
-The main release auditing tool, http://creadur.apache.org/rat[Apache RAT] is used in the xref:cg.adoc#_cg_committers_cutting-a-release[release process].
-
-Creadur's remaining tools - link:http://creadur.apache.org/tentacles/[Tentacles] and link:http://creadur.apache.org/whisker/[Whisker] - are to support the verification process.
-
-For example, Tentacles generates a report called `archives.html`. This lists all of the top-level binaires, their `LICENSE` and `NOTICE` files and any `LICENSE` and `NOTICE` files of any binaries they may contain.
-
-Validation of the output at this point is all still manual. Things to check include:
-
-* any binaries that contain no LICENSE and NOTICE files
-* any binaries that contain more than one LICENSE or NOTICE file
-
-In this report, each binary will have three links listed after its name '(licenses, notices, contents)'
-
-
-
-
-
-== Test the archetype
-
-Assuming that everything builds ok, then test the archetypes (adjust version as necessary):
-
-[source,bash]
-----
-mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D version=1.0-SNAPSHOT \
- -B \
- -o \
- -D archetypeVersion=1.12.0 # adjust version as necessary
-
-cd myapp
-mvn clean install -o
-mvn -P self-host antrun:run
-----
-
-If it runs up ok, then it's time to xref:cg.adoc#_cg_committers_verifying-releases[vote]!
-
-
-
-
-== Casting a Vote
-
-When you have made the above checks (and any other checks you think may be relevant), cast your vote by replying to the email thread on the mailing list.
-
-If you are casting `-1`, please provide details of the problem(s) you have found.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
deleted file mode 100644
index b0c0aba..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
+++ /dev/null
@@ -1,255 +0,0 @@
-[[_cg_contributing]]
-= Contributing
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-
-This page explains how you can contribute to Apache Isis. You'll probably also want xref:cg.adoc#_cg_ide[set up your IDE] and learn xref:cg.adoc#_cg_building-isis[how to build Apache Isis].
-
-Thanks for considering to help out, your contributions are appreciated!
-
-
-== Recommended Workflow (github)
-
-Apache Isis' source code is hosted in an Apache git repo (https://git-wip-us.apache.org/repos/asf/isis.git[https], http://git-wip-us.apache.org/repos/asf/isis.git[http]), with a clone on github (https://github.com/apache/isis.git[https], or ssh: `git@github.com:apache/isis.git`.
-
-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 https://github.com/apache/isis.git[apache/isis] repo in github, and then use your fork as a way of publishing your patches for the Apache Isis committers to apply.
-
-The diagram below illustrates the process:
-
-image::{_imagesdir}contributing/git-workflow.png[width="600px",link="{_imagesdir}contributing/git-workflow.png"]
-
-
-That is:
-
-. as a one-time activity, you fork the https://github.com/apache/isis.git[github.com/apache/isis] repo into your own fork on github.com
-. as a one-time activity, you clone your fork to your local computer
-. you set the https://github.com/apache/isis.git[github.com/apache/isis] 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
-. to contribute back a change, raise a https://issues.apache.org/jira/browse/ISIS[JIRA] ticket, and ensure your commit message is in the form: `ISIS-nnnn: ...` so that changes can be tracked (more discussion on this point below). In any case, before you decide to start hacking with Apache Isis, it's always worth creating a ticket in JIRA and then have a discussion about it on the http://isis.apache.org/support.html[mailing lists].
-. Use github to raise a https://help.github.com/articles/using-pull-requests/[pull request] for your feature
-. An Apache Isis committer will review your change, and apply it if suitable.
-
-
-
-
-== Alternative Workflow (JIRA patches)
-
-As an alternative, you may decide to clone directly from https://github.com/apache/isis.git[github.com/apache/isis] rather than create your own fork:
-
-
-image::{_imagesdir}contributing/git-workflow-2.png[width="600px",link="{_imagesdir}contributing/git-workflow-2.png"]
-
-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.
-
-For the Apache 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 https://github.com[github.com]. You then fork simply by pressing the "Fork" button:
-
-
-image::{_imagesdir}contributing/github-forking.png[width="600px",link="{_imagesdir}contributing/github-forking.png"]
-
-
-
-An account isn't needed if you just clone straight from the http://github.com/apache/isis[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:
-
-* 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:
-
-
-
-image::{_imagesdir}contributing/github-cloning.png[width="600px",link="{_imagesdir}contributing/github-cloning.png"]
-
-If you've created your own fork, then you need to add the `upstream` remote to the https://github.com/apache/isis[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:
-
-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:
-
-
-[source,bash]
-----
-git fetch
-----
-
-
-For more info on tracking branches http://git-scm.com/book/en/Git-Branching-Remote-Branches[here] and http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html[here].
-
-
-
-
-
-== 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 Apache 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]:
-
-[source,other]
-----
-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.
-----
-
-
-
-Once your git repo is setup, the next thing you'll most likely want to do is to setup your development environment. See link:development-environment.html[here] for more details.
-
-
-
-
-
-== Creating the patch file
-
-If you are working without a github fork of Apache Isis, then you can create the patches from your own local git repository.
-
-As per http://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit[this stackoverflow question], create the patch using `git format-patch`:
-
-[source,bash]
-----
-git format-patch -10 HEAD --stdout > 0001-last-10-commits.patch
-----
-
-Here `-10` is the last 10 commits you have done. You need to change that integer according to the commits you need to apply into the patch.
-
-
-
-
-== Sample Contribution Workflow
-
-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.
-
-=== Update your master branch
-
-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:
-
-Alternatively, you can combine the `git fetch` and `git merge` and just use `git pull`:
-<pre>
-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. You can use `gitk --all` to confirm. If this fails, see our link:git-cookbook.html[git cookbook] page for a procedure to retrospectively sort out this situation.
-
-
-
-=== 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"
-
-You can confirm the branch is there and is your new `HEAD` using either `gitk --all`. Alternatively, use the command line:
-
-
-[source,bash]
-----
-$ git checkout -b ISIS-123-blobs
-----
-
-
-The command line prompt should also indicate you are on a branch, isolated from any changes that might happen on the `master` branch.
-
-=== Make File Changes and Commit
-
-Next, make changes to your files using the usual commands (see also our xref:cg.adoc#_cg_git-cookbook[git cookbook] section):
-
-* `git add`
-* `git mv`
-* `git rm`
-* `git commit`
-* `git status`
-
-and so on.
-
-Continue this way until happy with the change. Remember to run all your tests on the topic branch (including a full `mvn clean install`).
-
-
-
-
-=== Rebasing with `master`
-
-Before you can share your change, you should rebase (in other words replay) your changes on top of the `master` branch.
-
-The first thing to do is to pull down any changes made in upstream remote's `master` since you started your topic branch:
-
-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.
-
-Next, we reintegrate our topic branch by rebasing onto `master`:
-<pre>
-git checkout ISIS-123-blobs
-git rebase master
-</pre>
-
-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.
-
-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:
-
-Once the rebase has completed, re-run your tests to confirm that everything is still good.
-
-
-
-=== Raising a pull request
-
-If you have your own fork, you can now simply push the changes you've made locally to your fork:
-
-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.
-
-Then, use github to raise a https://help.github.com/articles/using-pull-requests/[pull request]. Pull requests sent to the Apache GitHub repositories will forward a pull request e-mail to the link:../support.html[dev mailing list]. You'll probably want to sign up to the dev mailing list first before issuing your first pull request (though that isn't mandatory).
-
-The process to raise the pull request, broadly speaking:
-
-* 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 Apache Isis mailing list email came through.
-
-
-
-== If your pull request is accepted
-
-To double check that your pull request is accepted, update your `master` branch from the `upstream` remote:
-
-You can then use `gitk --all` (or `git log` if you prefer the command line) to check your contribution has been added.
-
-You can now delete your topic branch and remove the branch in your github:
-
-Finally, you might want to push the latest changes in master back up to your github fork. If so, use:
-
-
-
-=== If your pull request is rejected
-
-If your pull request is rejected, then you'll need to update your branch from the main repository and then address the rejection reason.
-
-You'll probably also want to remove the remote branch on github:
-
-[source,bash]
-----
-git push origin –delete ISIS-123-blobs
-----
-
-
-… and continue as before until you are ready to resubmit your change.
-
-[1] inspiration for the recommended commit format comes from the https://github.com/puppetlabs/puppet[puppet] project's https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md[contributing] page.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
deleted file mode 100644
index 1876e01..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
+++ /dev/null
@@ -1,258 +0,0 @@
-[[_cg_git-cookbook]]
-= Appendix: Git Cookbook
-: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.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-
-
-This appendix describes the commands often used while working with git. In addition to these basic commands, please make sure you have read:
-
-* xref:cg.adoc#_cg_building-isis[building Apache Isis]
-* xref:cg.adoc#_cg_policies_git-policy[Git policy]
-* xref:cg.adoc#_cg_contributing[Contributing]
-
-
-
-
-== Modifying existing files
-
-To modify existing files:
-
-[source,bash]
-----
-git add filename
-git commit -m "ISIS-nnn: yada yada"
-----
-
-The `git add` command adds the changes to the file(s) to the git index (aka staging area). If you were to make subsequent changes to the file these would not be committed.
-
-The `git commit` takes all the staged changes and commits them locally. Note that these changes are not shared public with Apache Isis' central git repo.
-
-You can combine these two commands using `-am` flag to git commit:
-
-[source,bash]
-----
-git commit -am "ISIS-nnn: yada yada"
-----
-
-
-
-
-== Adding new files
-
-To add a new file:
-
-[source,bash]
-----
-git add .
-git commit -m "ISIS-nnn: yada yada"
-----
-
-
-Note that this sequence of commands is identical to modifying an existing file. However, it isn't possible to combine the two steps using `git commit -am`; the `git add` is always needed when adding new files to the repo.
-
-
-
-
-== Deleting files
-
-To delete a file:
-
-[source,bash]
-----
-git rm filename
-git commit -m "ISIS-nnn: yada yada"
-----
-
-
-
-== Renaming or moving files
-
-To rename or move a file:
-
-
-[source,bash]
-----
-git mv <i>filename</i> <i>newfilename</i>
-git commit -m "ISIS-nnn: yada yada"
-----
-
-
-
-
-== Common Workflows
-
-The xref:cg.adoc#_cg_contributing[contributing] page describes the workflow for non-committers. The xref:cg.adoc#_cg_policies_git-policy[Git policy] page describes a workflow for Apache Isis **committers**.
-
-
-
-
-
-== Backing up a local branch
-
-If committing to a local branch, the changes are still just that: local, and run risk of a disk failure or other disaster.
-
-To create a new, similarly named branch on the central repo, use:
-
-[source,bash]
-----
-git push -u origin <i>branchname</i>
-----
-
-Using `gitk --all` will show you this new branch, named *origin/branchname*.
-
-Thereafter, you can push subsequent commits using simply:
-
-[source,bash]
-----
-git push
-----
-
-
-Doing this also allows others to collaborate on this branch, just as they would for `master`.
-
-When, eventually, you have reintegrated this branch, you can delete the remote branch using:
-
-[source,bash]
-----
-git push origin --delete <i>branchname</i>
-----
-
-
-For more detail, see these blogs/posts link:http://www.mariopareja.com/blog/archive/2010/01/11/how-to-push-a-new-local-branch-to-a-remote.aspx[here] and link:http://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-both-locally-and-in-github[here].
-
-
-
-== Quick change: stashing changes
-
-If you are working on something but are not ready to commit, then use:
-
-[source,bash]
-----
-git stash
-----
-
-
-If you use `gitk --all` then you'll see new commits are made that hold the current state of your working directory and staging area.
-
-You can then, for example, pull down the latest changes using `git pull --rebase` (see above).
-
-To reapply your stash, then use:
-
-[source,bash]
-----
-git stash pop
-----
-
-Note that stashing works even if switching branches
-
-
-## Ignoring files
-
-Put file patterns into `.gitignore`. There is one at the root of the git repo, but they can additionally appear in subdirectories (the results are cumulative).
-
-See also:
-
-- link:https://help.github.com/articles/ignoring-files[github's help page]
-- link:http://www.kernel.org/pub/software/scm/git/docs/gitignore.html[man page]
-
-
-
-
-== More advanced use cases
-
-=== If accidentally push to remote
-
-Suppose you committed to `master`, and then pushed the change, and then decided that you didn't intend to do that:
-
-[source,bash]
-----
-C1 - C2 - C3 - C4 - C5 - C6 - C7
- ^
- master
- ^
- origin/master
-----
-
-To go back to an earlier commit, first we wind back the local `master`:
-
-[source,bash]
-----
-git reset --hard C5
-----
-
-where `C5` is the long sha-id for that commit.
-
-This gets us to:
-
-[source,bash]
-----
-C1 - C2 - C3 - C4 - C5 - C6 - C7
- ^
- master
- ^
- origin/master
-----
-
-Then, do a force push:
-
-[source,bash]
-----
-git push origin master --force
-----
-
-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 link:http://stackoverflow.com/questions/1377845/git-reset-hard-and-a-remote-repository[here].
-
-
-
-
-== 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:
-
-[source,bash]
-----
-git branch <i>newbranch</i>
-----
-
-
-Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:
-
-
-[source,bash]
-----
-git stash
-----
-
-
-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:
-
-
-[source,bash]
-----
-git checkout master
-git reset --hard <i>shaId</i> # move master branch shaId of common ancestor
-----
-
-
-
-== If you've forgotten to prefix your commits (but not pushed)
-
-One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow. Using one of these, `git prefix`, you can just commit with proper message without bothering about prefix and add prefix only in the end *before* the final push.
-
-For example, to prefix all not yet prefixed commits `master..isis/666` with `ISIS-666` prefix, use:
-
-[source,bash]
-----
-git prefix ISIS-666 master..isis/666
-----
-
-
-You can grab this utility, and others, from link:https://github.com/themalkolm/git-boots[this repo].