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 2018/09/18 06:06:56 UTC
[isis] 01/02: ISIS-1899: updates docs re: publishing website
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit a2d8ba8fb2b665b0d6aeb513fd603dd66de1abdc
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Sep 18 06:06:21 2018 +0100
ISIS-1899: updates docs re: publishing website
---
adocs/documentation/README.adoc | 71 ++--------------------
.../src/main/asciidoc/__versions.adoc | 3 +-
.../cgcom/_cgcom_post-release-successful.adoc | 52 ++++++++--------
.../cgcom/_cgcom_post-release-unsuccessful.adoc | 26 ++++----
4 files changed, 47 insertions(+), 105 deletions(-)
diff --git a/adocs/documentation/README.adoc b/adocs/documentation/README.adoc
index 9059b61..362bab5 100644
--- a/adocs/documentation/README.adoc
+++ b/adocs/documentation/README.adoc
@@ -21,7 +21,8 @@ endif::env-github[]
This directory contains the source documentation that constitutes both the Apache Isis' documentation (meaning the website and the users' guide, the reference guide and contributors' guide) It is written using http://www.methods.co.nz/asciidoc/[Asciidoc], specifically the link:http://asciidoctor.org/[Asciidoctor] implementation.
-The website is created by running build tools (documented below) which create the HTML version of the site and guides. You can therefore easily check the documentation before raising a pull request
+The website is created by running build tools (documented below) which create the HTML version of the site and guides.
+You can therefore easily check the documentation before raising a pull request
So, if you want to contribute documentation - either just to fix a typo, or to write a how-to or longer article - then fork the repo, write or modify the the `.adoc` source file, and raise a pull request.
@@ -69,76 +70,16 @@ To (re)build the documentation locally prior to release, use:
[source]
----
-mvn clean compile
+sh preview-html.sh
----
-The site will be generated at `target/site/index.html`.
-
-You could then use a web server such as Python's SimpleHTTPServer to preview (so that all Javascript works correctly). However, instead we recommend using instant preview, described next.
-
-
-== Instant Rebuild (using Ruby)
-
-The ruby script, `monitor.rb` emulates the `mvn site` command, regenerating any changed Asciidoctor files to the relevant `target/site` directory. If any included files are changed then it rebuilds the parent (per the above naming convention).
-
-To setup:
-
-* download and install ruby 2.0.0, from link:http://rubyinstaller.org/downloads[http://rubyinstaller.org/downloads/]
-* download devkit for the Ruby 2.0 installation, also from link:http://rubyinstaller.org/downloads[http://rubyinstaller.org/downloads/]. Then follow the link:https://github.com/oneclick/rubyinstaller/wiki/Development-Kit[installation instructions] on their wiki
-
-
-[NOTE]
-====
-We use Ruby 2.0 rather than 2.1 because the wdm gem (required to monitor the filesystem if running on Windows) is not currently compatible with Ruby 2.1.
-====
-
-To install:
-
-[source,bash]
-----
-gem install bundler
-bundle install
-----
-
-To run, we typically just use:
-
-[source,bash]
-----
-ruby monitor.rb
-----
-
-This will start monitoring all files under `src/main/asciidoc`, and start up a web server on port 4000 so you can review results. If any `.adoc` changes, then the appropriate HTML will be regenerated. And, if any new assets (CSS, images etc) are added, they will be copied across.
-
-It often makes sense to combine this with `mvn`:
-
-[source,bash]
-----
-mvn clean install && ruby monitor.rb
-----
-
-This directory contains a tiny script, `r.sh`, that executes exactly the above line.
-
-The `monitor.rb` script has a couple of other options, use `-h` flag for usage:
-
-[source,bash]
-----
-ruby monitor.rb -h
-----
-
-which should print:
-
-[source]
-----
-usage: monitor.rb [options]
- -p, --port port (default: 4000)
- -b, --browser launch browser
- -h, --help help
-----
+The site will be generated at `target/site/index.html`, and then uses Python to start a webserver and a browser pointing at the site.
== Publish procedure
-Only Apache Isis committers can publish to link:http://isis.apache.org[isis.apache.org]. See the link:http://isis.apache.org/guides/cgcom.html#_cg_asciidoc[committers' guide] (including a longer version of this page) for details.
+Only Apache Isis committers can publish to link:http://isis.apache.org[isis.apache.org].
+See the link:http://isis.apache.org/guides/cgcom.html#_cg_asciidoc[committers' guide] for details.
diff --git a/adocs/documentation/src/main/asciidoc/__versions.adoc b/adocs/documentation/src/main/asciidoc/__versions.adoc
index 8b75b30..eceea95 100644
--- a/adocs/documentation/src/main/asciidoc/__versions.adoc
+++ b/adocs/documentation/src/main/asciidoc/__versions.adoc
@@ -1,4 +1,5 @@
:isiscurr: 1.16.2
:isisnext: 1.16.3
:isisnextafter: 1.16.4
-:isisdev: {isisnext}-SNAPSHOT
\ No newline at end of file
+:isisdev: {isisnext}-SNAPSHOT
+:isisdevafter: {isisnextafter}-SNAPSHOT
\ No newline at end of file
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
index b674d3b..42a089a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
@@ -25,9 +25,9 @@ This section describes the steps to perform if the vote has been successful.
Post the results to the `dev@isis.a.o` mailing list:
-[source,bash]
+[source,bash,subs="attributes+"]
----
-[RESULT] [VOTE] Apache Isis Core release 2.0.0-M1
+[RESULT] [VOTE] Apache Isis Core release {isisnext}
----
using the body (alter last line as appropriate):
@@ -55,11 +55,11 @@ Replace the `-RCn` tag with another without the qualifier.
You can do this using the `scripts/promoterctag.sh` script; for example:
-[source,bash]
+[source,bash,subs="attributes+"]
----
-sh scripts/promoterctag.sh isis-2.0.0-M1 RC1
-sh scripts/promoterctag.sh helloworld-archetype-2.0.0-M1 RC1
-sh scripts/promoterctag.sh simpleapp-archetype-2.0.0-M1 RC1
+sh scripts/promoterctag.sh isis-{isisnext} RC1
+sh scripts/promoterctag.sh helloworld-archetype-{isisnext} RC1
+sh scripts/promoterctag.sh simpleapp-archetype-{isisnext} RC1
----
This script pushes the tag under `refs/tags/rel`. As per Apache policy (communicated on 10th Jan 2016 to Apache PMCs),
@@ -222,9 +222,9 @@ If the files are invalid, then revert using `svn revert . --recursive` and try a
From the root directory, generate the release notes for the current release, in Asciidoc format; eg:
-[source,bash]
+[source,bash,subs="attributes+"]
----
-sh scripts/jira-release-notes.sh ISIS 2.0.0-M1 > /tmp/1
+sh scripts/jira-release-notes.sh ISIS {isisnext} > /tmp/1
----
@@ -260,7 +260,7 @@ In the main `isis` repo (ie containing the asciidoc source):
* 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 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:../../__versions.adoc[__versions.adoc] file that declares the current and next releases.
* Update the xref:../../downloads.adoc#[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])
@@ -279,12 +279,12 @@ For more information on DOAP files, see these http://projects.apache.org/doap.ht
Now we need to publish the website.
-* locate `template/document.html.erb` file, and remove `-SNAPSHOT` from the navbar:
+* locate `template/document.html.erb` file, and remove `-SNAPSHOT` from the navbar, so that it reads something like:
+
[source,html,subs="attributes+"]
----
-<p class="nav navbar-text navbar-right small">v2.0.0-M1</p>
+<p class="nav navbar-text navbar-right small">{isisnext}</p>
----
* publish to the `isis-site` repo.
@@ -313,9 +313,9 @@ mv content/versions/SNAPSHOT content/versions/current
+
For example:
+
-[source,bash]
+[source,bash,subs="attributes+"]
----
-cp -rf content/versions/current content/versions/2.0.0-M1
+cp -rf content/versions/current content/versions/{isisnext}
----
* update the new named version's `index.html` with one that will redirect back to the home page.
@@ -352,9 +352,9 @@ Therefore:
* locate `template/document.html.erb` file, and add in `-SNAPSHOT` for version in the navbar:
+
-[source,html]
+[source,html,subs="attributes+"]
----
-<p class="nav navbar-text navbar-right small">v2.0.0-M2-SNAPSHOT</p>
+<p class="nav navbar-text navbar-right small">{isisdevafter}</p>
----
* publish the website once more (from the `isis` main repo).
@@ -370,16 +370,16 @@ 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]
+[source,subs="attributes+"]
----
-[ANN] Apache Isis version 2.0.0-M1 Released
+[ANN] Apache Isis version {isisnext} Released
----
And use the following body (summarizing the main points as required):
-[source]
+[source,subs="attributes+"]
----
-The Apache Isis team is pleased to announce the release of Apache Isis v2.0.0-M1.
+The Apache Isis team is pleased to announce the release of Apache Isis {isisnext}.
New features in this release include:
* ...
@@ -394,8 +394,8 @@ Enjoy!
--The Apache Isis team
-[1] http://isis.apache.org/release-notes/release-notes.html#_release-notes_2.0.0-M1
-[2] http://isis.apache.org/migration-notes/migration-notes.html#_migration-notes_1.16.0-to-2.0.0-M1
+[1] http://isis.apache.org/release-notes/release-notes.html#_release-notes_{isisnext}
+[2] http://isis.apache.org/migration-notes/migration-notes.html#_migration-notes_{isiscurr}-to-{isisnext}
[3] http://search.maven.org
[4] http://isis.apache.org/downloads.html
----
@@ -416,17 +416,17 @@ Copy-n-paste the above mailing list announcement should suffice.
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]
+[source,bash,subs="attributes+"]
----
git checkout master # update master with latest
git pull
-git merge release-2.0.0-M1-RC1 # merge branch onto master
-git push origin --delete release-2.0.0-M1-RC1 # remote branch no longer needed
-git branch -d release-2.0.0-M1-RC1 # branch no longer needed
+git merge release-{isisnext}-RC1 # merge branch onto master
+git push origin --delete release-{isisnext}-RC1 # remote branch no longer needed
+git branch -d release-{isisnext}-RC1 # branch no longer needed
----
-Finally, update helloworld's `pom.xml` and simpleapp's root `pom.xml` to reference the next SNAPSHOT release (`2.0.0-M1-SNAPSHOT`)
+Finally, update helloworld's `pom.xml` and simpleapp's root `pom.xml` to reference the next SNAPSHOT release (`{isisdevafter}`)
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
index 6a6b2c7..11ac5e2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
@@ -24,14 +24,14 @@ 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]
+[source,bash,subs="attributes+"]
----
-[RESULT] [VOTE] Apache Isis Core release 2.0.0-M1
+[RESULT] [VOTE] Apache Isis Core release {isisnext}
----
using the body (alter last line as appropriate):
-[source,bash]
+[source,bash,subs="attributes+"]
----
The vote has completed with the following result :
@@ -51,29 +51,29 @@ Tidy up remote branches in the git repo:
* delete the remote branch, for example: +
+
-[source,bash]
+[source,bash,subs="attributes+"]
----
-git push --delete origin release-2.0.0-M1-RC1
+git push --delete origin release-{isisnext}-RC1
----
* delete the remote origin server's tags, for example: +
+
-[source,bash]
+[source,bash,subs="attributes+"]
----
-git push --delete origin isis-2.0.0-M1-RC1
-git push --delete origin helloworld-archetype-2.0.0-M1-RC1
-git push --delete origin simpleapp-archetype-2.0.0-M1-RC1
+git push --delete origin isis-{isisnext}-RC1
+git push --delete origin helloworld-archetype-{isisnext}-RC1
+git push --delete origin simpleapp-archetype-{isisnext}-RC1
----
* delete the tags that were created locally, for example: +
+
-[source,bash]
+[source,bash,subs="attributes+"]
----
-git tag -d isis-2.0.0-M1
-git tag -d helloworld-archetype-2.0.0-M1
-git tag -d simpleapp-archetype-2.0.0-M1
+git tag -d isis-{isisnext}
+git tag -d helloworld-archetype-{isisnext}
+git tag -d simpleapp-archetype-{isisnext}
----