ISIS-1465: adding docs for interim-release.sh and also bash_functions

Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2caea6fe
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2caea6fe
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2caea6fe

Branch: refs/heads/master
Commit: 2caea6fe4ce7beba2f2c902adb8ae27571f7486f
Parents: f2f7ced
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Fri Sep 9 11:17:20 2016 +0200
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Fri Sep 9 11:17:20 2016 +0200

----------------------------------------------------------------------
 .../src/main/asciidoc/downloads.adoc            |   2 +-
 ...om_release-process-for-interim-releases.adoc |  80 ++++++++++++++
 .../_cgcom_release-process-for-snapshots.adoc   |   4 +-
 .../guides/_dg_working-with-many-repos.adoc     | 110 +++++++++++++++++++
 .../src/main/asciidoc/guides/cgcom.adoc         |   1 +
 .../src/main/asciidoc/guides/dg.adoc            |   1 +
 6 files changed, 194 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2caea6fe/adocs/documentation/src/main/asciidoc/downloads.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/downloads.adoc 
b/adocs/documentation/src/main/asciidoc/downloads.adoc
index 1757c00..8e1cb6e 100644
--- a/adocs/documentation/src/main/asciidoc/downloads.adoc
+++ b/adocs/documentation/src/main/asciidoc/downloads.adoc
@@ -75,7 +75,7 @@ Alternatively, you can verify the MD5 signature on the files. 
A Unix/Linux progr
 
 
 
-
+[[_downloads_source_code]]
 == Source Code
 
 You can also download the Apache Isis source code using:

http://git-wip-us.apache.org/repos/asf/isis/blob/2caea6fe/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-interim-releases.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-interim-releases.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-interim-releases.adoc
new file mode 100644
index 0000000..401894d
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-interim-releases.adoc
@@ -0,0 +1,80 @@
+[[_cgcom_release-process-for-interim-releases]]
+= Interim 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
+
+
+The intent of an "interim" release is to allow a developer team to release 
their application based on a `-SNAPSHOT` version of the framework.  Since 
`-SNAPSHOT` changes on a day-to-day basis, the idea is to tag a particular 
revision and to release this, thereby providing stability/traceability for the 
application being developed.
+
+Whereas xref:cgcom.adoc#_cgcom_cutting-a-release.adoc[formal release]s and 
xref:cgcom.adoc#_cgcom_relesae-process-for-snapshots.adoc[snapshot release]s 
are public (released through the Maven repository maintained by Apache Software 
Foundation), interim releases are non-public and rely on infrastructure 
provided by a developer team.  The tagged release resides _not_ in the 
link:../downloads.adoc#_downloads_source_code[official Apache Isis git 
repository], but instead in a fork/clone maintained by the developer team.
+
+[NOTE]
+====
+The procedure developed here was put together for the team working on the 
link:../powered-by.adoc#_powered-by_estatio[Estatio app], which maintains its 
own link:https://github.com/incodehq/isis[fork on github] and uses 
link:https://www.cloudbees.com/[CloudBees] as a Jenkins build server/private 
Maven repo.
+====
+
+
+== Prerequisites
+
+Create a remote fork/clone of the Apache Isis repository (eg using 
link:http://github.com[github] or link:http://bitbucket.org[bitbucket] or 
similar), and ensure that your local fork specifies this remote.
+
+Also, set up a CI server against your fork/clone, to build against any 
branches called `origin/interim/*`.  To build it should use the command:
+
+[source,bash]
+----
+mvn clean install -Dskip.app -Dskip.arch
+----
+
+that is, skipping the example simpleapp and archetype; only `core` framework 
is built
+
+The CI server should then also publish the resultant artifacts to a local 
Maven repository.  For example, Jenkins provides post-build plugins to perform 
such a task.
+
+
+
+== Sanity Check
+
+Ensure that the framework builds ok using the same command that your CI server 
is set up to execute (see section above).
+
+
+
+== Release
+
+Deploy the framework using:
+
+[source,bsah]
+----
+sh interim-release.sh xxx yyyyy
+----
+
+where `xxx` is the most recent release of Isis (to act as the base), and 
`yyyyy` is the name of the remote.
+
+For example,
+
+[source,bash]
+----
+sh interim-release.sh 1.13.0 incodehq
+----
+
+This will result in a new branch and tagged being pushed to the remote, with 
an appropriate version (details below).
+
+As noted in the prereqs (above), the CI server configured should then detect 
the new branch (or tag, if you prefer), build the framework (skipping 
application and architecture, as in the prerequisites) and then publish the 
resultant artifacts to a private Maven repo.
+
+
+
+=== Implementation details
+
+The script itself:
+
+* removes any local branches called `interim/*`
+* creates a new branch called `interim/YYYYmmDD-HHMM`
+** eg `interim/1.13.0.20160909-0758`
+* updates the version of the pom.xml to the baseline plus the date
+** eg `<version>1.13.0.20160909-0758</version>`
+* commits the changes and tags the new commit
+** eg `isis-1.13.0.20160909-0758`
+* removes any remote branches called `interim/*`
+* pushes both the branch and the tag to the remote.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2caea6fe/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-snapshots.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-snapshots.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-snapshots.adoc
index 75764f7..4fdcd72 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-snapshots.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/_cgcom_release-process-for-snapshots.adoc
@@ -6,9 +6,7 @@
 :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.
+Snapshot releases allows the current `-SNAPSHOT` version of the `core` modules 
 of the framework to be released to the Maven snapshot repository maintained by 
Apache Software Foundation.
 
 [NOTE]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/2caea6fe/adocs/documentation/src/main/asciidoc/guides/_dg_working-with-many-repos.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/_dg_working-with-many-repos.adoc 
b/adocs/documentation/src/main/asciidoc/guides/_dg_working-with-many-repos.adoc
new file mode 100644
index 0000000..7564a57
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/_dg_working-with-many-repos.adoc
@@ -0,0 +1,110 @@
+[[_dg_working-with-many-repos]]
+= Appendix: Working with Many Repos
+: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
+
+
+Applications built with Apache Isis often (should) consist of multiple 
modules, each in separate git repositories.  For example, there are the various 
(non-ASF) link:http://isisaddons.org[Isis Addons] that provide various 
cross-cutting concerns/technical services (security, mail-merge etc), as well 
the modules eg as provided by the (non-ASF) 
link:http://catalog.incode.org[Incode Catalog], which provides generic business 
subdomains (communication channels, documents etc).
+
+In addition, your own application may well be structured as a number of 
distinct modules (probably with the entities in each module being mapped to a 
different schema), and using such techniques as the 
xref:ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus] and 
xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] so that these modules are 
decoupled from each other.
+
+All of which is a preamble to say that you will likely have multiple 
directories on your local development computer, for each such git repository 
that you contribute to.
+
+In this appendix we provide some simple but useful bash scripts to help you 
manage each such.
+
+
+== Prerequisites
+
+We recommend that you adopt a convention for your directories.  For example, 
open source repositories (such as the Isis Addons and Incode Catalog mentioned 
above) reside in link:https://github.com/[github.com], while your own 
proprietary code might reside in some other service, eg 
link:https://bitbucket.org/[bitbucket].  For example:
+
+[source]
+----
+/users/home/me/
+    BITBUCKET/
+        mycompany/
+            myapp-moduleA
+            myapp-moduleB
+            myapp
+    GITHUB/
+        isisaddons/
+            isis-module-docx
+            isis-module-security
+        incodehq/
+            incode-module-commchannel
+            incode-module-classification
+----
+
+
+== `_repos.txt`
+
+Create a file `_repos.txt` that catalogues the repositories, eg:
+
+[source]
+----
+#
+# our code
+#
+/users/home/me/BITBUCKET/mycompany/myapp-moduleA
+/users/home/me/BITBUCKET/mycompany/myapp-moduleB
+/users/home/me/BITBUCKET/mycompany/myapp
+#
+# open source modules
+#
+/users/home/me/GITHUB/isisaddons/isis-module-docx
+/users/home/me/GITHUB/isisaddons/isis-module-security
+/users/home/me/GITHUB/incodehq/incode-module-commchannel
+/users/home/me/GITHUB/incodehq/incode-module-classification
+----
+
+
+== Bash functions
+
+The `.bash_functions` file (downloadable from this 
link:https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c91cb[gist]) 
provides the following two functions:
+
+
+* `repo` +
++
+Switches (using `pushd`) to the specified directory (as listed in the 
`_repos.txt` file).
+
+* `foreach` +
++
+Runs the specified command for all (or matching) repositories (as listed in 
`_repos.txt` file).
+
+
+For example,
+
+[source,bash]
+----
+repo doc
+----
+
+would switch to `/users/home/me/GITHUB/isisaddons/isis-module-docx`, the first 
module that matches the fragment.
+
+
+Meanwhile:
+
+[source,bash]
+----
+foreach git status
+----
+
+would perform a `git status` on every git repository, while
+
+[source,bash]
+----
+foreach -g isisaddons git fetch
+----
+
+would perform a `git fetch` but only to those repositories which match 
"isisaddons" (`-g` flag standing for `grep`).
+
+
+To load the functions into your profile (`.bashrc` or `.profile` or similar), 
use:
+
+[source,bash]
+----
+. ~/.bash_functions
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2caea6fe/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc 
b/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
index 0e7856b..0fcfd41 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
@@ -53,6 +53,7 @@ include::_cgcom_verifying-releases.adoc[leveloffset=+1]
 include::_cgcom_post-release-successful.adoc[leveloffset=+1]
 include::_cgcom_post-release-unsuccessful.adoc[leveloffset=+1]
 include::_cgcom_release-process-for-snapshots.adoc[leveloffset=+1]
+include::_cgcom_release-process-for-interim-releases.adoc[leveloffset=+1]
 
 
 include::_cgcom_key-generation.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2caea6fe/adocs/documentation/src/main/asciidoc/guides/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg.adoc 
b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
index 0ec2373..8161614 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
@@ -60,6 +60,7 @@ include::_dg_asciidoc.adoc[leveloffset=+1]
 include::_dg_contributing.adoc[leveloffset=+1]
 
 include::_dg_git-cookbook.adoc[leveloffset=+1]
+include::_dg_working-with-many-repos.adoc[leveloffset=+1]
 include::_dg_asciidoc-templates.adoc[leveloffset=+1]
 include::_dg_project-lombok.adoc[leveloffset=+1]
 include::_dg_agilej.adoc[leveloffset=+1]

Reply via email to