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 2021/04/01 11:10:15 UTC
[isis] 04/05: ISIS-2484: updates committer guide
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 a6cea0dfcc68fdb84a977b302228f1da1382fca1
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Apr 1 12:09:29 2021 +0100
ISIS-2484: updates committer guide
---
antora/components/comguide/modules/ROOT/nav.adoc | 27 +++++---
.../ROOT/pages/post-release-successful.adoc | 79 +--------------------
.../modules/ROOT/pages/updating-the-website.adoc | 38 ++++++++++
.../ROOT/partials/publish-and-index-website.adoc | 80 ++++++++++++++++++++++
4 files changed, 135 insertions(+), 89 deletions(-)
diff --git a/antora/components/comguide/modules/ROOT/nav.adoc b/antora/components/comguide/modules/ROOT/nav.adoc
index b6723f8..9dc2600 100644
--- a/antora/components/comguide/modules/ROOT/nav.adoc
+++ b/antora/components/comguide/modules/ROOT/nav.adoc
@@ -1,14 +1,19 @@
: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 [...]
-* 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)]
-* xref:post-release-unsuccessful.adoc[Post Release (Unsuccessful)]
-* xref:key-generation.adoc[Key Generation]
-* xref:algolia-search.adoc[Appendix: Algolia Search]
-* xref:release-process-prereqs.adoc[Appendix: Release Process Prereqs]
-* xref:policies.adoc[Appendix: Policies]
-* xref:pmc-notes.adoc[Appendix: PMC Notes]
+* Occasionally
+** xref:merging-a-pull-request.adoc[Merging a Pull Request]
+** xref:applying-patches.adoc[Applying Patches]
+** xref:updating-the-website.adoc[Updating the Website]
+* Release
+** xref:cutting-a-release.adoc[Cutting a Release]
+** xref:verifying-releases.adoc[Verifying Releases]
+** Post Release
+*** xref:post-release-successful.adoc[Post Release (Successful)]
+*** xref:post-release-unsuccessful.adoc[Post Release (Unsuccessful)]
+* Appendices
+** xref:key-generation.adoc[Key Generation]
+** xref:algolia-search.adoc[Algolia Search]
+** xref:release-process-prereqs.adoc[Release Process Prereqs]
+** xref:policies.adoc[Policies]
+** xref:pmc-notes.adoc[PMC Notes]
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 086e784..c04ecd3 100644
--- a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
@@ -385,86 +385,9 @@ Finally, revert the last commit (backing out changes to `site.yml`):
git revert HEAD
----
-[#publish-website]
-== Publish website
-We now copy the results of the Antora website generation over to the `isis-site` repo:
+include::partial$publish-and-index-website.adoc[]
-* in the `isis-site` repo, check out the `asf-site` branch:
-+
-[source,bash,subs="attributes+"]
-----
-cd ../isis-site
-
-git checkout asf-site
-git pull --ff-only
-----
-
-* still in the `isis-site` repo, delete all the files in `content/` _except_ for the `schema` and `versions` directories:
-+
-[source,bash,subs="attributes+"]
-----
-pushd content
-for a in $(ls -1 | grep -v schema | grep -v versions)
-do
- rm -rf $a
-done
-popd
-----
-
-* Copy the generated Antora site to `isis-site` repo's `contents` directory:
-+
-[source,bash,subs="attributes+"]
-----
-cd ../isis
-
-cp -Rf antora/target/site/* ../isis-site/content/.
-----
-
-* Back in the `isis-site` repo, commit the changes and preview:
-+
-[source,bash,subs="attributes+"]
-----
-cd ../isis-site
-
-git add .
-git commit -m "$ISISJIRA : production changes to website"
-
-sh preview.sh
-----
-
-* If everything looks ok, then push the changes to make live, and switch back to the `isis` repo:
-+
-[source,bash,subs="attributes+"]
-----
-git push origin asf-site
-----
-
-[#update-the-algolia-search-index]
-== Update the Algolia search index
-
-Create a `algolia.env` file holding the `APP_ID` and the admin `API_KEY`, in the root of `isis-site`:
-
-[source,ini]
-.algolia.env
-----
-APPLICATION_ID=...
-API_KEY=...
-----
-
-CAUTION: This file should not be checked into the repo, because the API_KEY allows the index to be modified or deleted.
-
-We use the Algolia-provided link:https://hub.docker.com/r/algolia/docsearch-scraper[docker image] for the crawler to perform the search (as per the link:as per https://docsearch.algolia.com/docs/run-your-own/#run-the-crawl-from-the-docker-image[docs]):
-
-[source,bash]
-----
-cd content
-docker run -it --env-file=../algolia.env -e "CONFIG=$(cat ../algolia-config.json | jq -r tostring)" algolia/docsearch-scraper
-----
-
-This posts the index up to the link:https://algolia.com[Algolia] site.
-
-NOTE: Additional config options for the crawler can be found link:https://www.algolia.com/doc/api-reference/crawler/[here].
== Merge in release branch
diff --git a/antora/components/comguide/modules/ROOT/pages/updating-the-website.adoc b/antora/components/comguide/modules/ROOT/pages/updating-the-website.adoc
new file mode 100644
index 0000000..63748b0
--- /dev/null
+++ b/antora/components/comguide/modules/ROOT/pages/updating-the-website.adoc
@@ -0,0 +1,38 @@
+= Updating the Website
+
+: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:
+
+As part of the release process we xref:post-release-successful.adoc#generate-website[generate] and publish the website.
+An (intentional) side-effect of this process is to create a branch for the release (that is, `{page-isisrel}`).
+This branch can then be used for documentation updates.
+
+== Update docs
+
+In the regular `isis` repo:
+
+* Check out the branch:
++
+[source,bash,subs="attributes+"]
+----
+git checkout {page-isisrel}
+----
+
+* make documentation updates, and commit changes
+
+* generate the website:
++
+[source,bash,subs="attributes+"]
+----
+sh preview.sh
+----
++
+This will write to `antora/target/site`; we'll use the results in the xref:#publish-website[next section].
++
+NOTE: this requires Java 11 for the projdoc tooling.
+
+
+
+
+include::partial$publish-and-index-website.adoc[]
+
diff --git a/antora/components/comguide/modules/ROOT/partials/publish-and-index-website.adoc b/antora/components/comguide/modules/ROOT/partials/publish-and-index-website.adoc
new file mode 100644
index 0000000..89bcb8b
--- /dev/null
+++ b/antora/components/comguide/modules/ROOT/partials/publish-and-index-website.adoc
@@ -0,0 +1,80 @@
+[#publish-website]
+== Publish website
+
+We now copy the results of the Antora website generation over to the `isis-site` repo:
+
+* in the `isis-site` repo, check out the `asf-site` branch:
++
+[source,bash,subs="attributes+"]
+----
+cd ../isis-site
+
+git checkout asf-site
+git pull --ff-only
+----
+
+* still in the `isis-site` repo, delete all the files in `content/` _except_ for the `schema` and `versions` directories:
++
+[source,bash,subs="attributes+"]
+----
+pushd content
+for a in $(ls -1 | grep -v schema | grep -v versions)
+do
+ rm -rf $a
+done
+popd
+----
+
+* Copy the generated Antora site to `isis-site` repo's `contents` directory:
++
+[source,bash,subs="attributes+"]
+----
+cd ../isis
+
+cp -Rf antora/target/site/* ../isis-site/content/.
+----
+
+* Back in the `isis-site` repo, commit the changes and preview:
++
+[source,bash,subs="attributes+"]
+----
+cd ../isis-site
+
+git add .
+git commit -m "$ISISJIRA : production changes to website"
+
+sh preview.sh
+----
+
+* If everything looks ok, then push the changes to make live, and switch back to the `isis` repo:
++
+[source,bash,subs="attributes+"]
+----
+git push origin asf-site
+----
+
+[#update-the-algolia-search-index]
+== Update the Algolia search index
+
+Create a `algolia.env` file holding the `APP_ID` and the admin `API_KEY`, in the root of `isis-site`:
+
+[source,ini]
+.algolia.env
+----
+APPLICATION_ID=...
+API_KEY=...
+----
+
+CAUTION: This file should not be checked into the repo, because the API_KEY allows the index to be modified or deleted.
+
+We use the Algolia-provided link:https://hub.docker.com/r/algolia/docsearch-scraper[docker image] for the crawler to perform the search (as per the link:as per https://docsearch.algolia.com/docs/run-your-own/#run-the-crawl-from-the-docker-image[docs]):
+
+[source,bash]
+----
+cd content
+docker run -it --env-file=../algolia.env -e "CONFIG=$(cat ../algolia-config.json | jq -r tostring)" algolia/docsearch-scraper
+----
+
+This posts the index up to the link:https://algolia.com[Algolia] site.
+
+NOTE: Additional config options for the crawler can be found link:https://www.algolia.com/doc/api-reference/crawler/[here].