jspwiki-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From juanpa...@apache.org
Subject jspwiki-site git commit: reflow + explain the CI and Maven build scripts
Date Tue, 20 Jun 2017 19:31:48 GMT
Repository: jspwiki-site
Updated Branches:
  refs/heads/jbake 666992f58 -> d2448759a


reflow + explain the CI and Maven build scripts


Project: http://git-wip-us.apache.org/repos/asf/jspwiki-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/jspwiki-site/commit/d2448759
Tree: http://git-wip-us.apache.org/repos/asf/jspwiki-site/tree/d2448759
Diff: http://git-wip-us.apache.org/repos/asf/jspwiki-site/diff/d2448759

Branch: refs/heads/jbake
Commit: d2448759a52c838fad74dd4efdc5ebc42c764b40
Parents: 666992f
Author: Juan Pablo Santos Rodriguez <juanpablo@apache.org>
Authored: Tue Jun 20 21:31:35 2017 +0200
Committer: Juan Pablo Santos Rodriguez <juanpablo@apache.org>
Committed: Tue Jun 20 21:31:35 2017 +0200

----------------------------------------------------------------------
 README.md                                       | 61 +++++++++++---------
 .../jbake/content/development/edit_website.md   | 60 ++++++++++++++-----
 2 files changed, 79 insertions(+), 42 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/jspwiki-site/blob/d2448759/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 5bce292..fb811f0 100755
--- a/README.md
+++ b/README.md
@@ -4,16 +4,16 @@ Apache JSPWiki website
 (adapted from [Apache Guacamole site](https://github.com/apache/incubator-guacamole-website))
 
 This repository contains the source for the website of Apache JSPWiki, so it 
-can be deployed via gitpubsub (see https://issues.apache.org/jira/browse/INFRA-13716)
+can be deployed via [gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available)

+(see https://issues.apache.org/jira/browse/INFRA-13716)
 
-The website itself is completely static, being automatically generated by
-[JBake](https://jbake.org/) prior to deployment. The content of the website
-is written in a mixture of Freemarker templates and Markdown. Templated
-content is interpreted only a build time, with the final result being
+The website itself is completely static, being automatically generated by [JBake](https://jbake.org/)

+prior to deployment. The content of the website is written in a mixture of Freemarker templates
and 
+Markdown. Templated content is interpreted only at build time, with the final result being

 completely static.
 
-To facilitate ease of development and testing, this repository also contains a
-build script, `build.sh`, the usage of which is documented below.
+To facilitate ease of development and testing, this repository also contains a couple of
+build scripts, `ci.sh` and `mvn-ci.sh`, the usage of which is documented below.
 
 Table of contents
 -----------------
@@ -26,12 +26,14 @@ Table of contents
 Repository structure
 --------------------
 
-In addition to the `LICENSE` and `NOTICE` files required of any proper Apache-
-licensed project, the repository contains the following critical files:
+In addition to the `LICENSE` and `NOTICE` files required of any proper Apache-licensed project,

+the repository contains the following critical files:
 
 | Filename            | Description
 | -------------       | -----------
 | `./pom.xml`         | to orchestrate the website build
+| `./ci.sh`           | script, meant to be run by a CI server, to build and deploy the website.
+| `./mvn-ci.sh`       | script to build and deploy the website using Maven.
 | `./src/main/jbake/` | standard [jbake maven plugin structure](https://github.com/ingenieux/jbake-maven-plugin),
contains three subdirectories:
 |  -> `assets/`       | The assets directory is where you should place your static files
such as images, CSS files and JavaScript files etc. These files are copied over to the baked
output as is. You can create any directory structure you like in the assets directory and
this structure will be maintained when copied.
 |  -> `content/`      | holds content files, with the extension of these files determining
what type of content it contains (i.e.: `.md` for [Markdown](http://daringfireball.net/projects/markdown/syntax),
`.html` for raw HTML, etc.)
@@ -41,40 +43,45 @@ licensed project, the repository contains the following critical files:
 Build prerequisites
 -------------------
 
-The build needs at least Maven 3.1.1 and Java 7, thus these must be installed first.
+The CI build (`ci.sh`) needs Java 7 and a JBake installation under `$JBAKE_HOME`. This 
+script is run at [ASF's Jenkins instance](https://builds.apache.org/job/jspwiki-site/). 
+As there isn't a Maven installation at the nodes which perform this job, this script 
+only takes the changes from the "jbake" branch, generates the site and puts it on the 
+"asf-site" branch. As for now, javadocs must be pushed locally through the Maven build 
+script.
+
+The Maven build (`mvn-ci.sh`) needs at least Maven 3.1.1 and Java 7, thus these must 
+be installed first. It's essentially the same build as the CI build, but done through 
+Maven. This allows us to generate the site and also put the javadocs in there.
 
 Testing changes locally
 -----------------------
+
 Just run `mvn clean jbake:inline` and the site will be accesible through http://localhost:8080.

 Changes will be reloaded on the fly. When done testing your local changes, press `Enter`
to stop 
 the web server and return to the shell.
 
 Publishing changes
 ------------------
+
 Changes to the website are published using Apache's 
 [gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available) which relies
on a 
-special branch called "asf-site" containing *all website content* within a directory called

-`./content/`.
+special branch called "asf-site" containing *all website content*.
 
 In the Apache JSPWiki website repository, the "asf-site" branch is an "orphan" branch. Updating

 the website thus involves:
 
 1. Making and testing your changes locally
-2. Replacing the entire contents of the `content/` directory within "asf-site"
-   with the newly-generated `content/` directory.
-
-On the `jbake` branch, run `mvn clean generate-resources` to generate the site under 
-`./target/content/`. Move the site to the `./content/` directory on the `asf-site` 
-branch and push the generated site there.
+2. Replacing the entire contents within "asf-site" with the newly-generated site from the

+   "jbake" branch.
 
-Keep in mind that the new content must be *staged* for and committed in this branch. 
-Once you have verified that the staged content is as expected, commit your changes 
-(along with a useful commit message describing the changes at a high level) using 
-`git commit` and publish the update using `git push origin`.
+Second step is automated through `ci.sh` and `mvn-ci.sh` scripts. 
 
-If you wish to unstage your changes, use `git reset --hard HEAD` to return to the 
-original state of "asf-site", wiping out any local modifications. You can then return 
-to whichever branch you were working on with `git checkout`.
+Keep in mind that the new content must be *staged* for and committed in this branch. Once
you have 
+verified that the staged content is as expected, commit your changes (along with a useful
commit 
+message describing the changes at a high level) using `git commit` and publish the update
using 
+`git push origin`.
 
-Use `ci.sh` on the `jbake` branch after executing `mvn clean generate-resources` 
-to automate all this procedure.
\ No newline at end of file
+If you wish to unstage your changes, use `git reset --hard HEAD` to return to the original
state 
+of "jbake", wiping out any local modifications. You can then return to whichever branch you

+were working on with `git checkout`.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/jspwiki-site/blob/d2448759/src/main/jbake/content/development/edit_website.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/development/edit_website.md b/src/main/jbake/content/development/edit_website.md
index 843db0e..5085b8d 100755
--- a/src/main/jbake/content/development/edit_website.md
+++ b/src/main/jbake/content/development/edit_website.md
@@ -5,14 +5,24 @@ type=page
 ~~~~~~
 Apache JSPWiki website
 ----------------------
+
 (adapted from [Apache Guacamole site](https://github.com/apache/incubator-guacamole-website))
 
-This repository contains the source for the website of Apache JSPWiki, so it can be deployed
via [gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available) (see https://issues.apache.org/jira/browse/INFRA-13716)
+This repository contains the source for the website of Apache JSPWiki, so it 
+can be deployed via [gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available)

+(see https://issues.apache.org/jira/browse/INFRA-13716)
+
+The website itself is completely static, being automatically generated by [JBake](https://jbake.org/)

+prior to deployment. The content of the website is written in a mixture of Freemarker templates
and 
+Markdown. Templated content is interpreted only at build time, with the final result being

+completely static.
 
-The website itself is completely static, being automatically generated by [JBake](https://jbake.org/)
prior to deployment. The content of the website is written in a mixture of Freemarker templates
and Markdown. Templated content is interpreted only a build time, with the final result being
completely static.
+To facilitate ease of development and testing, this repository also contains a couple of
+build scripts, `ci.sh` and `mvn-ci.sh`, the usage of which is documented below.
 
 Table of contents
 -----------------
+
 * [Repository structure](#repository-structure)
 * [Build prerequisites](#build-prerequisites)
 * [Testing changes locally](#testing-changes-locally)
@@ -20,9 +30,12 @@ Table of contents
 
 ## Repository structure<a name="repository-structure"></a>
 
-In addition to the `LICENSE` and `NOTICE` files required of any proper Apache-licensed project,
the repository contains the following critical files:
+In addition to the `LICENSE` and `NOTICE` files required of any proper Apache-licensed project,

+the repository contains the following critical files:
 
-* `./pom.xml`: to orchestrate the website build
+* `./pom.xml`: orchestrates the maven website build
+* `./ci.sh`: script, meant to be run by a CI server, to build and deploy the website.
+* `./mvn-ci.sh`: script to build and deploy the website using Maven.
 * `./src/main/jbake/`: standard [jbake maven plugin structure](https://github.com/ingenieux/jbake-maven-plugin),
contains three subdirectories:
     * `./src/main/jbake/assets/`: The assets directory is where you should place your static
files such as images, CSS files and JavaScript files etc. These files are copied over to the
baked output as is. You can create any directory structure you like in the assets directory
and this structure will be maintained when copied.
     * `./src/main/jbake/content/`: holds content files, with the extension of these files
determining what type of content it contains (i.e.: `.md` for [Markdown](http://daringfireball.net/projects/markdown/syntax),
`.html` for raw HTML, etc.)
@@ -31,26 +44,43 @@ In addition to the `LICENSE` and `NOTICE` files required of any proper
Apache-li
 
 ## Build prerequisites<a name="build-prerequisites"></a>
 
-The build needs at least Maven 3.1.1 and Java 7, thus these must be installed first.
+The CI build (`ci.sh`) needs Java 7 and a JBake installation under `$JBAKE_HOME`. This 
+script is run at [ASF's Jenkins instance](https://builds.apache.org/job/jspwiki-site/). 
+As there isn't a Maven installation at the nodes which perform this job, this script 
+only takes the changes from the "jbake" branch, generates the site and puts it on the 
+"asf-site" branch. As for now, javadocs must be pushed locally through the Maven build 
+script.
+
+The Maven build (`mvn-ci.sh`) needs at least Maven 3.1.1 and Java 7, thus these must 
+be installed first. It's essentially the same build as the CI build, but done through 
+Maven. This allows us to generate the site and also put the javadocs in there.
 
 ## Testing changes locally<a name="testing-changes-locally"></a>
 
-Just run `mvn clean jbake:inline` and the site will be accesible through http://localhost:8080.
Changes will be reloaded on the fly. When done testing your local changes, press `Enter` to
stop the web server and return to the shell.
+Just run `mvn clean jbake:inline` and the site will be accesible through http://localhost:8080.

+Changes will be reloaded on the fly. When done testing your local changes, press `Enter`
to stop 
+the web server and return to the shell.
 
 ## Publishing changes<a name="publishing-changes"></a>
 
-Changes to the website are published using Apache's [gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available)
which relies on a special branch called "asf-site" containing *all website content* within
a directory called `./content/`.
+Changes to the website are published using Apache's 
+[gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available) which relies
on a 
+special branch called "asf-site" containing *all website content*.
 
-In the Apache JSPWiki website repository, the "asf-site" branch is an "orphan" branch. Updating
the website thus involves:
+In the Apache JSPWiki website repository, the "asf-site" branch is an "orphan" branch. Updating

+the website thus involves:
 
 1. Making and testing your changes locally
-2. Replacing the entire contents of the `content/` directory within "asf-site"
-   with the newly-generated `content/` directory.
-
-On the `jbake` branch, run `mvn clean generate-resources` to generate the site under `./target/content/`.
Move the site to the `./content/` directory on the `asf-site` branch and push the generated
site there.
+2. Replacing the entire contents within "asf-site" with the newly-generated site from the

+   "jbake" branch.
 
-Keep in mind that the new content must be *staged* for and committed in this branch. Once
you have verified that the staged content is as expected, commit your changes (along with
a useful commit message describing the changes at a high level) using `git commit` and publish
the update using `git push origin`.
+Second step is automated through `ci.sh` and `mvn-ci.sh` scripts. 
 
-If you wish to unstage your changes, use `git reset --hard HEAD` to return to the original
state of "asf-site", wiping out any local modifications. You can then return to whichever
branch you were working on with `git checkout`.
+Keep in mind that the new content must be *staged* for and committed in this branch. Once
you have 
+verified that the staged content is as expected, commit your changes (along with a useful
commit 
+message describing the changes at a high level) using `git commit` and publish the update
using 
+`git push origin`.
 
-Use `ci.sh` on the `jbake` branch after executing `mvn clean generate-resources` to automate
all this procedure.
\ No newline at end of file
+If you wish to unstage your changes, use `git reset --hard HEAD` to return to the original
state 
+of "jbake", wiping out any local modifications. You can then return to whichever branch you

+were working on with `git checkout`.


Mime
View raw message