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 2020/03/16 17:14:34 UTC
[isis] 01/41: ISIS-2062: improves comguide docs
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2278
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 39dcc586e9f4534c2c0216c17f976214710c6397
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Mar 6 15:34:02 2020 +0000
ISIS-2062: improves comguide docs
---
antora/components/comguide/modules/ROOT/nav.adoc | 2 +-
.../comguide/modules/ROOT/pages/about.adoc | 2 +-
.../ROOT/pages/antora-publish-procedure.adoc | 6 +-
.../modules/ROOT/pages/applying-patches.adoc | 56 ++++++++-----------
.../modules/ROOT/pages/cutting-a-release.adoc | 7 ++-
.../modules/ROOT/pages/key-generation.adoc | 64 ++++++++++++----------
.../modules/ROOT/pages/merging-a-pull-request.adoc | 35 ++++--------
.../comguide/modules/ROOT/pages/pmc-notes.adoc | 23 +-------
.../comguide/modules/ROOT/pages/policies.adoc | 1 -
.../modules/ROOT/pages/policies/git-policy.adoc | 18 ++----
.../ROOT/pages/policies/versioning-policy.adoc | 29 +++-------
.../ROOT/pages/post-release-successful.adoc | 7 ---
.../ROOT/pages/post-release-unsuccessful.adoc | 6 --
.../ROOT/pages/release-process-for-snapshots.adoc | 14 ++---
.../ROOT/pages/release-process-prereqs.adoc | 12 +---
.../modules/ROOT/pages/verifying-releases.adoc | 17 ------
preview.sh | 12 +++-
17 files changed, 111 insertions(+), 200 deletions(-)
diff --git a/antora/components/comguide/modules/ROOT/nav.adoc b/antora/components/comguide/modules/ROOT/nav.adoc
index 1cb1278..ebd9206 100644
--- a/antora/components/comguide/modules/ROOT/nav.adoc
+++ b/antora/components/comguide/modules/ROOT/nav.adoc
@@ -1,5 +1,5 @@
-* xref:applying-patches.adoc[Applying Patches]
* xref:merging-a-pull-request.adoc[Merging a Pull Request]
+* xref:applying-patches.adoc[Applying Patches]
* xref:cutting-a-release.adoc[Cutting a Release]
* xref:verifying-releases.adoc[Verifying Releases]
* xref:post-release-successful.adoc[Post Release (Successful)]
diff --git a/antora/components/comguide/modules/ROOT/pages/about.adoc b/antora/components/comguide/modules/ROOT/pages/about.adoc
index 756d259..12e3f75 100644
--- a/antora/components/comguide/modules/ROOT/pages/about.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/about.adoc
@@ -1,6 +1,6 @@
= Committers' Guide
: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 ag [...]
-
+:page-role: -toc
This committers' guide is for committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.
diff --git a/antora/components/comguide/modules/ROOT/pages/antora-publish-procedure.adoc b/antora/components/comguide/modules/ROOT/pages/antora-publish-procedure.adoc
index 565de32..3bfd6c0 100644
--- a/antora/components/comguide/modules/ROOT/pages/antora-publish-procedure.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/antora-publish-procedure.adoc
@@ -18,8 +18,6 @@ Publishing is performed by copying the generated HTML to a different git reposit
This is synced by ASF infrastructure over to link:http://isis.apache.org[isis.apache.org].
This can only be done by Apache Isis committers, and is discussed below.
-
-
== One-time setup
The generated site is published by copying into the `content/` directory of the https://github.com/apache/isis-site.git[isis-site] git repo.
@@ -51,7 +49,6 @@ Therefore, in the `isis.git` repo site:
git checkout asf-site
----
-
== Preview
To preview changes (ignoring PDFs), run:
@@ -72,7 +69,6 @@ sh preview-pdf.sh
There's generally little point in doing this, however.
-
== Publishing (full build)
The `content` directory for the published website contains not only the "current version" of the docs, but also has an archive of older versions of the document from earlier releases:
@@ -135,7 +131,7 @@ When a new release is published, we therefore need to do a little extra work:
* run `publish.sh` a first time
+
-This will update `content/versions/SNAPSHOT`
+This will update `content/versions/SNAPSHOT`
* delete `content/versions/current`
* rename `content/versions/SNAPSHOT` to `content/versions/current`
* run `publish.sh` a second time.
diff --git a/antora/components/comguide/modules/ROOT/pages/applying-patches.adoc b/antora/components/comguide/modules/ROOT/pages/applying-patches.adoc
index 26689df..d3a43af 100644
--- a/antora/components/comguide/modules/ROOT/pages/applying-patches.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/applying-patches.adoc
@@ -4,50 +4,33 @@
:page-partial:
+If a patch is received on a JIRA ticket, then it should be reviewed and applied using command line tools.
+== Inspect the patch
-
-
-If a patch is received on a JIRA ticket, then it should be reviewed and applied. The commands are slightly different for diff files vs patch files.
-
-
-
-
-== Diff files
-
-If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)…
-
-NOTE: FIXME - this stuff needs fleshing out ...
-
-
-
-
-== Patch files
-
-If a patch file has been provided, then it can be applied using command line tools.
-
-=== Inspect the patch
-
-First, take a look at what changes are in the patch. You can do this easily with `git apply`
+First, take a look at what changes are in the patch.
+You can do this easily with `git apply`
[source,bash]
----
git apply --stat ISIS-xxx.patch
----
-Note that this command does not apply the patch, but only shows you the stats about what it’ll do. After peeking into the patch file with your favorite editor, you can see what the actual changes are.
+Note that this command does not apply the patch, but only shows you the stats about what it’ll do.
+After peeking into the patch file with your favorite editor, you can see what the actual changes are.
-Next, you're interested in how troublesome the patch is going to be. Git allows you to test the patch before you actually apply it.
+Next, you're interested in how troublesome the patch is going to be.
+Git allows you to test the patch before you actually apply it.
[source,bash]
----
git apply --check ISIS-xxx.patch
----
-If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble you’ll run into.
-
+If you don't get any errors, the patch has no conflicts.
+Otherwise you may see what trouble you’ll run into.
-=== Apply a (clean) patch
+== Apply a (clean) patch
To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`:
@@ -58,7 +41,8 @@ git am --signoff < ISIS-xxx.patch
This preserves the original author's commit message.
-However, this can fail if the patch file does not contain the original committers email address. In this case you will need to abort the `am` session:
+However, this can fail if the patch file does not contain the original committers email address.
+In this case you will need to abort the `am` session:
[source,bash]
----
@@ -67,18 +51,18 @@ git am abort
and continue on by applying a non-clean patch, as described next.
+== Apply a (non-clean) patch
-
-=== Apply a (non-clean) patch
-
-If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is:
+If the patch does not apply cleanly, then the original authors commit message cannot be preserved.
+This sequence in this case is:
[source,bash]
----
git apply ISIS-xxx.patch
----
-Fix up any issues. The add and commit as usual
+Fix up any issues.
+The add and commit as usual
[source,bash]
----
@@ -89,3 +73,7 @@ git commit -am "<original authors' commit message>" --signoff
The `--signoff` simply adds a line to the commit message indicating you have signed off the commit.
Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page].
+
+== Diff files
+
+If a diff file has been provided instead of a patch, then use for example the eGit's wizards (Eclipse's Git integration).
diff --git a/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc b/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc
index cfe69d58..a92f24f 100644
--- a/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc
@@ -22,11 +22,14 @@ They should work on Linux and MacOS; for Windows, use mSysGit.
== Obtain Consensus
-Before releasing the framework, ensure there is consensus on the xref:docs:ROOT:support.adoc#[dev mailing list] that this is the right time for a release.
+
+Before releasing the framework, ensure there is consensus on the xref:docs:support:mailing-list.adoc[dev mailing list] that this is the right time for a release.
The discussion should include confirming the version number to be used, and to confirm content.
These discussions should also confirm the version number of the module being released.
-This should be in line with our xref:comguide:ROOT:versioning-policy.adoc[semantic versioning policy].
+This should be in line with our xref:comguide:ROOT:policies/versioning-policy.adoc#semantic-versioning[semantic versioning policy].
+
+
Make sure you have a JIRA ticket open against which to perform all commits.
In most cases a JIRA ticket will have been created at the beginning of the previous release cycle.
diff --git a/antora/components/comguide/modules/ROOT/pages/key-generation.adoc b/antora/components/comguide/modules/ROOT/pages/key-generation.adoc
index aa019a2..adf4897 100644
--- a/antora/components/comguide/modules/ROOT/pages/key-generation.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/key-generation.adoc
@@ -12,8 +12,6 @@ In order that a contributor can make a release it is necessary for them to have
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.
@@ -27,12 +25,10 @@ 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:
+The Apache Software Foundation requires that keys are signed with a key (or subkey) based on RSA 4096 bits.
+To do this:
[source]
----
@@ -153,9 +149,11 @@ To confirm the key has been generated, use:
$ 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`).
+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:
+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]
----
@@ -163,7 +161,8 @@ $ gpg --edit-key nnnnnnnnn
>gpg
----
-where `nnnnnnnn` is your key id. Now, use the 'showpref' subcommand to list details:
+where `nnnnnnnn` is your key id.
+Now, use the 'showpref' subcommand to list details:
[source]
----
@@ -177,7 +176,8 @@ gpg> showpref
gpg>
----
-The Digest line should list SHA-512 first and SHA-1 last. If it doesn't, use the "setpref" command:
+The Digest line should list SHA-512 first and SHA-1 last.
+If it doesn't, use the "setpref" command:
[source]
----
@@ -188,15 +188,16 @@ Finally, remember to take a backup of your key and the keyring (ie, backup the `
== 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.
+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.
+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]
@@ -232,7 +233,6 @@ Select (6) to choose an RSA key for encryption:
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
@@ -279,7 +279,8 @@ 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.
+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:
@@ -368,13 +369,12 @@ 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:
+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]
----
@@ -383,18 +383,22 @@ $ 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:
+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`).
+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 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:
@@ -415,11 +419,13 @@ 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.
+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.
+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:
@@ -533,11 +539,13 @@ Log onto `id.apache.org` and ensure that the finger print of your public key is
== 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].
+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.
+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:
diff --git a/antora/components/comguide/modules/ROOT/pages/merging-a-pull-request.adoc b/antora/components/comguide/modules/ROOT/pages/merging-a-pull-request.adoc
index 2dcb043..2d57175 100644
--- a/antora/components/comguide/modules/ROOT/pages/merging-a-pull-request.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/merging-a-pull-request.adoc
@@ -9,11 +9,8 @@
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 will merge the fork into a temporary branch, and then run a build.
+Once you are happy, you can commit.
== Process and Usage
@@ -28,10 +25,9 @@ The overall process is as follows:
This link:https://youtu.be/CKSLZBBHjME[screencast] also shows the process.
-
== Prerequisites
-The script uses 'jq' to parse JSON. To install:
+The script uses 'jq' to parse JSON. To install:
* on Linux: +
+
@@ -48,10 +44,7 @@ brew install jq
----
* on Windows: +
-+
-Download exe from http://stedolan.github.io/jq/download/[website]
-
-
++ Download exe from http://stedolan.github.io/jq/download/[website]
== Syntax
@@ -65,22 +58,16 @@ github-pr.sh -j 1162 -g 31 [-s] [-p ISIS]
where:
* `-j 1162` +
-+
-is the JIRA ticket number
++ is the JIRA ticket number
* `-g 31` +
-+
-is the github PR issue number
++ is the github PR issue number
* `-s` +
-+
-will optionally skip the build and auto-merge
++ will optionally skip the build and auto-merge
* `-p ISIS` +
-+
-optionally overrids the JIRA project (defaults to 'ISIS')
-
-
++ optionally overrids the JIRA project (defaults to 'ISIS')
== Example transcript
@@ -116,7 +103,8 @@ Merge made by the 'recursive' strategy.
Merged the PR; hit enter to build
----
-The build now commences. Once done, the script continues:
+The build now commences.
+Once done, the script continues:
[source,bash]
----
@@ -131,7 +119,8 @@ image::committers/github-pr-history.png[link="{imagesdir}/committers/github-pr-h
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.
+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.
diff --git a/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc b/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc
index 3c6d69a..cba4d94 100644
--- a/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc
@@ -1,4 +1,3 @@
-[[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 ag [...]
:page-partial:
@@ -15,8 +14,6 @@ In Apache Isis, every committer is a member of the PMC.
This page contains some general notes on maintenance activities required by PMC members.
-
-
== Prereqs
To complete the procedures documented here, you'll need `ssh` access to `minotaur.apache.org`.
@@ -34,8 +31,6 @@ When prompted, provide passphrase for private key.
To set up ssh in the first place, take a look at https://www.apache.org/dev/new-committers-guide.html#ssh-setup[this section in the ASF new committers' guide] looks relevant.
====
-
-
== New Committer/PMC member
Currently we don't distinguish between committers and PMC members: every committer is automatically invited to also be a member of the PMC.
@@ -73,8 +68,6 @@ http://www.timeanddate.com/countdown/to?year=YYYY&month=MM&day=DD
By convention, we run these votes for 7 days (a minimum of 3 days is required by ASF).
-
-
=== Close the vote, announce results
After the 7 days has expired, close the vote thread.
@@ -114,17 +107,13 @@ I'll announce to users@ and dev@ by separate thread.
----
<1> update as required
-
-
=== ICLA, obtain new account
-If required (that is, if the committer is not already a committer for a different ASF project),
-then ask them to complete an ICLA.
+If required (that is, if the committer is not already a committer for a different ASF project), then ask them to complete an ICLA.
As a result of this, they should also get an @apache.org user name.
More info can be found in the https://www.apache.org/dev/new-committers-guide.html#icla-required-before-account-creation[ASF new committers guide].
-
=== Update the `isis` unix group
All committers must be added to the `isis` UNIX group.
@@ -166,12 +155,10 @@ modify_committee.pl isis --add joebloggs
<1> update as required
* second, update `committee-info.txt` +
-+
-This is held in SVN, under https://svn.apache.org/repos/private[https://svn.apache.org/repos/private]; the file resides at `committers/board/committee-info.txt`
++ This is held in SVN, under https://svn.apache.org/repos/private[https://svn.apache.org/repos/private]; the file resides at `committers/board/committee-info.txt`
The new committer does not officially become a member of the PMC until the ASF records have been updated.
-
=== Notify the ASF board and private mailing list
Send a `[NOTICE]` email to `board@apache.org` and also to `private@isis.apache.org`
@@ -205,13 +192,10 @@ The committee-info.txt file has been updated, as have the LDAP groups (modify_un
update the private threads above
====
-
=== Update project metadata
Update the `STATUS` file (in the root directory of the Apache Isis git repo) with the new committer details.
-
-
=== Announce to the world
Send an `[ANNOUNCE]` email TO `users@isis.apache.org` and to `dev@isis.apache.org`.
@@ -244,9 +228,6 @@ Apache Isis PMC Chair
Also, write a similar blog post at https://blogs.apache.org/isis[blogs.apache.org/isis]
-
-
-
== Removing a committer
[WARNING]
diff --git a/antora/components/comguide/modules/ROOT/pages/policies.adoc b/antora/components/comguide/modules/ROOT/pages/policies.adoc
index 9744cc9..ed7b700 100644
--- a/antora/components/comguide/modules/ROOT/pages/policies.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/policies.adoc
@@ -1,4 +1,3 @@
-[[policies]]
= Policies
: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 ag [...]
:page-partial:
diff --git a/antora/components/comguide/modules/ROOT/pages/policies/git-policy.adoc b/antora/components/comguide/modules/ROOT/pages/policies/git-policy.adoc
index ea19041..06fcfe6 100644
--- a/antora/components/comguide/modules/ROOT/pages/policies/git-policy.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/policies/git-policy.adoc
@@ -5,10 +5,8 @@
-
-
-
-These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
+These notes recommend how contributors should work with git.
+To understand these notes, the only real concepts that you need to grok are:
* git commits form an acyclic graph, with each commit pointing to its parent commit (or commit**s**, if a merge)
@@ -24,8 +22,6 @@ For more background reading, see:
And, of course, there is loads of good advice on http://stackoverflow.com/questions/tagged/git[stackoverflow.com]
-
-
== Workflow
There are many ways of using Git, but the Apache Isis committers have adopted the following workflow:
@@ -44,10 +40,9 @@ git checkout -b ISIS-999
git push origin ISIS-999
----
-
* `rebase` the topic branch periodically on master. +
-+
-How often you do this will depend on whether you are collaborating with others on the feature. You need to ensure that your co-worker has no outstanding work before you do this; otherwise it'll create merge conflict hell for them:
++ How often you do this will depend on whether you are collaborating with others on the feature.
+You need to ensure that your co-worker has no outstanding work before you do this; otherwise it'll create merge conflict hell for them:
+
[source,bash]
----
@@ -76,10 +71,6 @@ git push origin --delete ISIS-999
This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to `master` to see the ultimate impact of the changes (acting a bit like a summary).
-
-
-
-
== Commit message
The minimum we expect in a commit messages is:
@@ -93,7 +84,6 @@ ISIS-nnn: brief summary here
- in bullet points
----
-
where `ISIS-nnn` is a ticket raised in our https://issues.apache.org/jira/browse/ISIS[JIRA issue tracker].
For non-committers we typically expect more detail again; see the xref:conguide:ROOT:contributing.adoc[contributing] page for the longer format recommended for contributors to use.
diff --git a/antora/components/comguide/modules/ROOT/pages/policies/versioning-policy.adoc b/antora/components/comguide/modules/ROOT/pages/policies/versioning-policy.adoc
index ac2d89c..71011d9 100644
--- a/antora/components/comguide/modules/ROOT/pages/policies/versioning-policy.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/policies/versioning-policy.adoc
@@ -1,36 +1,25 @@
-[[versioning-policy]]
= Versioning Policy
:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or ag [...]
:page-partial:
-
-
-
-
-
-
-
-## Semantic Versioning
+== Semantic Versioning
Starting from v1.0.0, Apache Isis has adopted link:http://semver.org[semantic versioning] for its versioning policy.
Version numbers are in the form `x.y.z`:
-- x is bumped up whenever there a breaking API change
-- y is bumped up whenever there is a new feature that does not break API
-- z is bumped up for minor bug fixes.
+* x is bumped up whenever there a breaking API change
+* y is bumped up whenever there is a new feature that does not break API
+* z is bumped up for minor bug fixes.
This scheme would be adopted for both core and components.
+== Version ranges
+Version ranges may not be used.
+If necessary, end-users can use `<dependencyManagement>` elements to have combine components built against different versions of core.
-
-
-
-## Version ranges
-
-Version ranges may not be used. If necessary, end-users can use `<dependencyManagement` elements to have combine components built against different versions of core.
-
-That said, this can introduce instability and so generally we recommend that end-users configure the `maven-enforcer-plugin` and its link:http://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html[DependencyConvergence] rule. This will help avoid "jar hell" (components having conflicting dependencies of core).
+That said, this can introduce instability and so generally we recommend that end-users configure the `maven-enforcer-plugin` and its link:http://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html[DependencyConvergence] rule.
+This will help avoid "jar hell" (components having conflicting dependencies of core).
If there is a conflict, we would ask that end-users engage with Apache Isis committers to have an updated version of the component(s) pushed out.
diff --git a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
index abbf63f..b631e62 100644
--- a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
@@ -1,13 +1,7 @@
-[[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 ag [...]
:page-partial:
-
-
-
-
-
The release process consists of:
* the release manager xref:comguide:ROOT:cutting-a-release.adoc[cutting the release]
@@ -72,7 +66,6 @@ image::release-process/nexus-release-1.png[width="600px",link="{imagesdir}/relea
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].
diff --git a/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc b/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc
index 6ee5256..80325c2 100644
--- a/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc
@@ -1,13 +1,7 @@
-[[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 ag [...]
:page-partial:
-
-
-
-
-
The release process consists of:
* the release manager xref:comguide:ROOT:cutting-a-release.adoc[cutting the release]
diff --git a/antora/components/comguide/modules/ROOT/pages/release-process-for-snapshots.adoc b/antora/components/comguide/modules/ROOT/pages/release-process-for-snapshots.adoc
index 4b3b9c2..c1d3fe7 100644
--- a/antora/components/comguide/modules/ROOT/pages/release-process-for-snapshots.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/release-process-for-snapshots.adoc
@@ -8,14 +8,13 @@
-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.
+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]
====
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:
@@ -36,14 +35,13 @@ Before you start, make sure you've defined the snapshots repo in your local `~/.
</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].
+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].
+{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.
@@ -65,8 +63,6 @@ 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:
diff --git a/antora/components/comguide/modules/ROOT/pages/release-process-prereqs.adoc b/antora/components/comguide/modules/ROOT/pages/release-process-prereqs.adoc
index b8d520d..8e89864 100644
--- a/antora/components/comguide/modules/ROOT/pages/release-process-prereqs.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/release-process-prereqs.adoc
@@ -11,15 +11,11 @@
This section (appendix) describes the prerequisites for the xref:comguide:ROOT:release-process.adoc[release process].
-
-
== Configure toolchains plugin
Apache Isis releases are built using Java 7, enforced using the maven toolchains plugin.
Ensure that Java 7 is installed and the toolchains plugin is configured, as described in the xref:conguide:ROOT:building-apache-isis.adoc#configure-maven-toolchains-plugin[contributors' guide].
-
-
== Public/private key
The most important configuration you require is to set up public/private key pair.
@@ -28,7 +24,6 @@ See the page on xref:comguide:ROOT:key-generation.adoc[key generation] for more
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`.
@@ -39,11 +34,10 @@ Note also that the mSysGit version of `gpg.exe` (as provided by GitHub's bash cl
If you use Atlassian's SourceTree, this also bundles a version of `gpg.exe` that is not compatible (in `C:\Users\xxx\AppData\Local\Atlassian\SourceTree\git_local\usr\bin`); again, move it to one side and instead use the one provided by 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:
+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]
----
@@ -63,14 +57,12 @@ During the release process the `maven-deploy-plugin` uploads the generated artif
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]
diff --git a/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc b/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc
index 3442136..ad5d9a0 100644
--- a/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc
@@ -16,8 +16,6 @@ The release process consists of:
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:comguide:ROOT:release-process.adoc[release process]) on the xref:docs:ROOT:support.adoc#[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release.
@@ -33,8 +31,6 @@ Note that the binaries are _not_ an ASF release, they merely exist on the Maven
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
You will also require the following commands/tools:
@@ -61,14 +57,11 @@ to unzip the ZIP files
+
to build the code
-
-
== Verifying source artifacts
The easiest way to verify the source artifacts is to use a script that automates the steps.
Run these commands (they should also be listed in the VOTE email):
-
[source,bash,subs="attributes+"]
----
NEXUSREPONUM=10xx # <1>
@@ -102,12 +95,9 @@ in other words, to confirm that the release was created by an Apache Isis commit
Assuming this completes successfully, you can then test the two starter applications; adjust the version if required.
-
You can if you wish perform some additional optional checks, listed in the sections below.
Alternatively, you can xref:comguide:ROOT:verifying-releases.adoc#casting-a-vote[cast your vote].
-
-
== (Optional) 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 xref:docs:starters:helloworld.adoc[HelloWorld starter app] or the xref:docs:starters:simpleapp.adoc[SimpleApp starter app] (adjust the parent version if required).
@@ -148,11 +138,6 @@ If there is more than one repository (as is sometimes the case if multiple compo
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.
-
-
-
-
-
== (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.
@@ -172,8 +157,6 @@ Things to check include:
In this report, each binary will have three links listed after its name '(licenses, notices, contents)'
-
-
== 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.
diff --git a/preview.sh b/preview.sh
index ce91c72..db93942 100644
--- a/preview.sh
+++ b/preview.sh
@@ -1,7 +1,9 @@
#!/usr/bin/env bash
+export ANTORA_CACHE_DIR=.antora-cache-dir
+
PLAYBOOK_FILE=antora/playbooks/site.yml
-while getopts 'ecf:aksh' opt
+while getopts 'ecf:aksxh' opt
do
case $opt in
e) export SKIP_EXAMPLES=true ;;
@@ -10,6 +12,7 @@ do
a) export SKIP_GENERATION=true ;;
k) export SKIP_STALE_EXAMPLE_CHECK=true ;;
s) export SKIP_SERVE=true ;;
+ x) export SKIP_CLEAR_CACHE=true ;;
h) echo ""
echo "preview.sh options:"
echo " -e skip examples"
@@ -17,6 +20,7 @@ do
echo " -c skip config doc generation"
echo " -a skip Antora generation"
echo " -s skip serving generated site"
+ echo " -x skip clear Antora cache"
echo " -f antora/playbooks/site-xxx.yml"
exit 1
;;
@@ -26,6 +30,12 @@ do
esac
done
+if [[ "$SKIP_CLEAR_CACHE" == "true" ]]; then
+ echo "skipping clearing the Antora cache"
+else
+ rm -rf $ANTORA_CACHE_DIR
+fi
+
if [ ! -f $PLAYBOOK_FILE ]; then
echo "no such file $PLAYBOOK_FILE" >&2
exit 1