You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shiro.apache.org by bm...@apache.org on 2021/09/08 20:12:24 UTC
[shiro-site] 03/06: [README] move and convert readme,
add CONTRIBUTING.adoc.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit c974bbe9c5ff986ea1fd79a1d8c5f8f7ade75a63
Author: Benjamin Marwell <bm...@apache.org>
AuthorDate: Mon Sep 6 07:17:27 2021 +0200
[README] move and convert readme, add CONTRIBUTING.adoc.
---
README.md | 32 ----------------------------
jbake/CONTRIBUTING.adoc | 36 +++++++++++++++++++++++++++++++
jbake/README.adoc | 40 +++++++++++++++++++++++++++++++++++
jbake/content/10-minute-tutorial.adoc | 1 -
4 files changed, 76 insertions(+), 33 deletions(-)
diff --git a/README.md b/README.md
deleted file mode 100644
index f5c2683..0000000
--- a/README.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Apache Shiro Website Overview
-
-The Apache Shiro website is a static content website accessible at http://shiro.apache.org
-
-Site content is authored as Markdown and HTML files. These files are scanned by a tool that applies a page template to each file's contents as necessary, and the rendered static .html files are output to a `dest_dir` directory.
-
-To publish the site commit changes to the `asf-site` branch of this repository. ASF infrastructure will see the commit and automatically push the changes to the ASF's production webservers.
-
-## Generating and Publishing
-
-The tool used to generate the static content is [SCMS](https://github.com/lhazlewood/scms). Once scms is installed and in your `$PATH`, generating and publishing the site on the command line is easy.
-
-The following example assumes you have commit permissions to the `apache/shiro-site` repository, typically because your are an Apache Shiro project committer:
-
- # clone both repo branches `asf-site` and `main`
- git clone https://github.com/apache/shiro-site -b asf-site shiro-site-publish
- git clone https://github.com/apache/shiro-site
-
- # build the site
- cd shiro-site
- scms . ../shiro-site-publish
- # Open up the local ../shiro-site-publish/index.html file in your web browser. Ensure the changes reflect what you want.
-
- # These next commands will publish changes to live ASF web servers. Be confident the changes are what you want:
- cd ../shiro-site-publish
- git add .
- git commit -am "my change description"
- git push origin asf-site
-
- # It should only take a few minutes until the files are live
-
-
diff --git a/jbake/CONTRIBUTING.adoc b/jbake/CONTRIBUTING.adoc
new file mode 100644
index 0000000..b902c1b
--- /dev/null
+++ b/jbake/CONTRIBUTING.adoc
@@ -0,0 +1,36 @@
+= Apache Shiro Site: Contributing
+
+== General guidelines
+
+* New files are written in AsciiDoc, using `.adoc` filename extensions.
+* Each sentence ends with a newline (`\n`).
+Git will automatically convert line endings for you.
+
+
+== Changes for a new Apache Shiro Release
+
+=== Changes to link:data/releases.yaml[]
+
+* If the new `latestRelease` is a new minor release (e.g. `1.x.0`), prepend the old version to the `oldReleases` array. +
+Please skip this step for minor releases.
+* If the new `latestRelease` is a minor release, update the version number of the `releases` object at the end of the file. +
+_Rationale:_ Every minor release should only be represented with the latest bugfix release.
+* Change `latestRelease: "..."` to the new version.
+* Update the `versionInfo` object accordingly. +
+You can just add a new release, there is no need to remove old releases.
+
+=== Changes to link:data/artifacts.yaml[]
+
+In the unlikely event that new artifacts were generated, please modify link:data/artifacts.yaml[] according to your needs. +
+Do not delete artifacts, as they may be in use for old versions.
+
+After modifying the artifacts file, update the `releases` object in link:data/releases.yaml[] to include the new artifact's name.
+
+== Development server
+
+To start a development server on http://localhost:8820, use this command:
+
+[source,bash]
+----
+mvn clean jbake:inline
+----
diff --git a/jbake/README.adoc b/jbake/README.adoc
new file mode 100644
index 0000000..128ab55
--- /dev/null
+++ b/jbake/README.adoc
@@ -0,0 +1,40 @@
+= Apache Shiro Website Overview
+
+The Apache Shiro website is a static content website accessible at http://shiro.apache.org/.
+
+Site content is authored as Markdown, Asciidoc and HTML files.
+These files are parsed by the tool `jbake` and renders the content files using freemarker templates to static `.html` files.
+
+To publish the site commit changes to the `asf-site` branch of this repository.
+ASF infrastructure will see the commit and automatically push the changes to the ASF͘'s production webservers.
+
+== Generating and Publishing
+
+The tool used to generate the static content is https://jbake.org/[JBake].
+JBake is used as a maven plugin, i.e. you do not need to have it in your `${PATH}`.
+Generating and publishing the site on the command only takes a few maven and git commands.
+Please carefully check the requirements outlined in link:CONTRIBUTING.adoc[].
+
+The following example assumes you have commit permissions to the `apache/shiro-site` repository, typically because you are an Apache Shiro project committer:
+
+[source,bash]
+----
+# clone both repo branches `asf-site` and `main`
+git clone https://github.com/apache/shiro-site -b asf-site shiro-site-publish
+git clone https://github.com/apache/shiro-site
+
+# build the site
+cd shiro-site
+mvn clean generate-resources
+# Open up the local ../shiro-site-publish/index.html file in your web browser.
+# Ensure the changes reflect what you want.
+
+# These next commands will publish changes to live ASF web servers.
+# Be confident the changes are what you want:
+cd ../shiro-site-publish
+git add .
+git commit -am "my change description"
+git push origin asf-site
+----
+
+It should only take a few moments until the changes are live.
diff --git a/jbake/content/10-minute-tutorial.adoc b/jbake/content/10-minute-tutorial.adoc
index d203baf..d565fd2 100644
--- a/jbake/content/10-minute-tutorial.adoc
+++ b/jbake/content/10-minute-tutorial.adoc
@@ -220,4 +220,3 @@ Then can move onto other link:documentation.html[Documentation,title="Documentat
You'll also probably want to join the user link:mailing-lists.html[mailing list,title="Mailing Lists"] - you'll find that we have a great community with people willing to help whenever possible.
Thanks for following along.We hope you enjoy using Apache Shiro!
-