This is an automated email from the ASF dual-hosted git repository.
ctubbsii pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/accumulo-website.git
The following commit(s) were added to refs/heads/master by this push:
new d4439a3 Update README to use asf-staging (#217)
d4439a3 is described below
commit d4439a39cbd56a5524fcfe8b89c0f17471d8fe38
Author: Christopher Tubbs <ctubb...@apache.org>
AuthorDate: Tue Jan 28 16:04:06 2020 -0500
Update README to use asf-staging (#217)
---
.asf.yaml | 2 +-
.travis.yml | 1 +
README.md | 196 ++++++++++++++++++++++++++--------------
_devtools/git-hooks/post-commit | 57 ------------
4 files changed, 129 insertions(+), 127 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
index 74795e5..d85c77d 100644
--- a/.asf.yaml
+++ b/.asf.yaml
@@ -7,7 +7,7 @@ publish:
whoami: asf-site
github:
- description: "Apache Accumulo website"
+ description: "Apache Accumulo Website"
homepage: https://accumulo.apache.org/
labels:
- accumulo
diff --git a/.travis.yml b/.travis.yml
index cb0c989..bd4eac4 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -4,5 +4,6 @@ rvm:
branches:
except:
- asf-site
+ - asf-staging
cache: bundler
script: ./_devtools/cibuild
diff --git a/README.md b/README.md
index e54582b..190655f 100644
--- a/README.md
+++ b/README.md
@@ -1,47 +1,20 @@
# Apache Accumulo Website
-Apache Accumulo uses [Jekyll] to build their website. It is recommended that
you
-use [Bundler] to install the necessary dependencies to run and build the
website.
+Apache Accumulo's website is generated from Markdown source (specifically,
+[kramdown] style) with [Jekyll], using [Bundler] to manage its gem
+dependencies.
-## Install Bundler and dependencies
+## Development
-Ruby is required to use Bundler so first make sure you have Ruby on your
machine. If you are using
-an OS packaged version of Ruby, you will have to also install the ruby-dev
(Ubuntu) or
-ruby-devel (Fedora) package as well. Depending on your OS, you may also need
other packages, such as
-ruby-full, make, gcc, nodejs, build-essentials, or patch.
+### Custom Liquid Tags
-With Ruby installed on your machine, you can install [Bundler] using the
command below:
+Jekyll uses [Liquid] to process files before interpreting their Markdown
+contents. We have extended Jekyll using its plugin mechanism to create custom
+Liquid tags that make it easier to link to javadocs, properties, and documents.
- gem install bundler
+The source for these tags is at [\_plugins/links.rb](_plugins/links.rb).
-Next, use [Bundler] to install [Jekyll] and other dependencies needed to run
the website.
-
- git clone https://github.com/apache/accumulo-website
- cd accumulo-website
- bundle install
-
-## Run the website locally
-
-Run the following command to run the website locally using Jekyll's embedded
webserver:
-
- cd accumulo-website
- bundle exec jekyll serve -w
-
-The website can viewed at [http://0.0.0.0:4000/](http://0.0.0.0:4000/)
-
-## Build website static HTML files
-
-You can just build static HTML files which are viewable in `_config.yml`:
-
- cd accumulo-website
- bundle exec jekyll build
-
-## Custom liquid tags
-
-Custom liquid tags are used to make linking to javadocs, properties, and
documents easier.
-The source for these tags is at [_plugins/links.rb](_plugins/links.rb).
-
-| Tag | Description | Options
| Examples
|
+| Tag | Description | Options
| Examples
|
| ----- | ---------------------- |
-------------------------------------------------------------------------------
| ---------------------------------------------------- |
| jlink | Creates Javadoc link | Link text will be class name by default.
Use `-f` for full package + class name | `{% jlink -f
org.apache.accumulo.core.client.Connector %}` `{% jlink -f
org.apache.accumulo.core.client %}` |
| jurl | Creates Javadoc URL | None
| `{% jurl
org.apache.accumulo.core.client.Connector %}` |
@@ -53,54 +26,139 @@ The source for these tags is at
[_plugins/links.rb](_plugins/links.rb).
| ghc | GitHub code link | Branch defaults to `gh_branch` setting
in `_config.yml`. Override using `-b` | `{% ghc
server/tserver/src/main/java/org/apache/accumulo/tserver/TabletServer.java %}`
`{% ghc -b 1.9 README.md %}` |
| jira | Jira issue link | None | `{% jira ACCUMULO-1000 %}` |
-## Updating property documentation
+### Updating Property Documentation for Releases
-Building Accumulo generates `server-properties.md` and
`client-properties.md`. To
-regenerate these, do the following.
+Building Accumulo generates `server-properties.md` and `client-properties.md`.
+To regenerate these, do the following.
-```
-cd <accumulo source dir>
+```bash
+ACCUMULO_SITE_CLONE=<accumulo website clone location, with master branch
checked out>
+ACCUMULO_CLONE=<accumulo clone location>
+cd "$ACCUMULO_CLONE"
mvn package -DskipTests
-cp ./core/target/generated-docs/server-properties.md <accumulo website
source>/_docs-2/configuration
-cp ./core/target/generated-docs/client-properties.md <accumulo website
source>/_docs-2/configuration
+cp ./core/target/generated-docs/server-properties.md
"$ACCUMULO_SITE_CLONE"/_docs-2/configuration
+cp ./core/target/generated-docs/client-properties.md
"$ACCUMULO_SITE_CLONE"/_docs-2/configuration
```
-## Update the production website
+## Local Builds for Testing
+
+### Setting up Your Jekyll/Bundler Environment
+
+Ruby and RubyGems are required to use Jekyll and Bundler, so first make sure
+you have those on your machine.
-For Apache Accumulo committers, the `asf-site` branch needs to be updated with
the generated
-HTML. Changes to this branch are automagically mirrored to the website.
+If you are using an OS packaged version of Ruby, you may also need to install
+the ruby-dev (Ubuntu) or ruby-devel (Fedora) package as well to build any
+native code for gems that are installed later. Installing these will also
+ensure your system's RubyGems package is installed. Depending on your OS, you
+may also need other packages to install/build gems, such as ruby-full, make,
+gcc, nodejs, build-essentials, or patch.
-This can be done easily by invoking the post-commit hook (either by hand, or
automatically via configuring
-Git to invoke the post-commit hook). The commands below are a guide for
committers who wish to publish
-the web site.
+Once Ruby, RubyGems, and any necessary native tools are installed, you are
+ready to install [Bundler] to manage the remaining RubyGem dependencies.
+Bundler is included in Ruby 2.6 and later as a default gem, so installing it
+may not be needed.
+
+Because we use [Bundler] to install specific versions of gems, it is not
+recommended to use an OS packaged version of gems other than what comes
+built-in. If you are using an OS packaged version of Ruby, it is __strongly__
+recommended to avoid `sudo` when installing additional gems, in order to avoid
+conflicting with your system's package-managed installation. Instead, you can
+specify a `GEM_HOME` directory for installing gems locally in your home
+directory. You can do this in your `$HOME/.bashrc` file or other appropriate
+place for your environment:
```bash
-# ensure local asf-site branch is up to date
-git checkout asf-site
-git pull upstream asf-site
+# in .bashrc
+export GEM_HOME=$HOME/.gem/ruby
+```
-# switch to master branch, update it, and build new site
-git checkout master
-git pull upstream master
-./_devtools/git-hooks/post-commit
+With Ruby installed on your machine, you can install [Bundler] using the
+command below:
-# switch to asf-site, look at the commit created by post-commit script, and
push it if ok
-git checkout asf-site
-git log -p
-git push upstream asf-site
+```bash
+# not necessary in Ruby >2.6, since it is a default gem since 2.6
+gem install bundler
```
-In the commands above `upstream` is :
+
+Next, use [Bundler] to install [Jekyll] and other dependencies needed to run
+the website (this command assumes your current working directory is your clone
+of this repository with the `master` branch checked out, because that's where
+the Gemfile dependency list exists).
```bash
-$ git remote -v | grep upstream
-upstream https://gitbox.apache.org/repos/asf/accumulo-website/ (fetch)
-upstream https://gitbox.apache.org/repos/asf/accumulo-website/ (push)
+bundle install
```
-To automatically run this post-commit hook in your local repository, copy
-the given file into your `.git/hook` directory:
+### Testing with the Built-in Jekyll Webserver
+
+The command to serve the site contents using Jekyll's built-in webserver is as
+follows (this webserver may behave differently than apache.org's servers).
+
+```bash
+bundle exec jekyll serve -w
+```
+
+You do __NOT__ need to execute a `bundle exec jekyll build` command first, as
+the `serve` command is sufficient to both build the site and serve its
+contents. By default, it will also try to re-build any pages you change while
+running the webserver, which can be quite useful if trying to get some CSS or
+HTML styled "just right".
+
+Jekyll will print a local URL where the site can be viewed (usually,
+[http://0.0.0.0:4000/](http://0.0.0.0:4000/)).
+
+## Publishing
+
+### Automatic Staging
+
+Changes pushed to our `master` branch will automatically trigger Jekyll to
+build our site from that branch and push the result to our `asf-staging`
+branch, where they will be served on [our default staging site][staging].
+
+### Publishing Staging to Production
+
+First, add our repository as a remote in your local clone, if you haven't
+already done so (these commands assume the name of that remote is 'upstream').
+
+Example:
+
+```bash
+git clone https://github.com/<yourusername>/accumulo-website
+cd accumulo-website
+git remote add upstream https://github.com/apache/accumulo-website
+```
+
+Next, publish the staging site to production by updating the `asf-site` branch
+to match the contents in the `asf-staging` branch:
+
+```bash
+# Step 0: stay in master branch; you never need to switch
+git checkout master
+
+# Step 1: update your upstream remote
+git remote update upstream
+
+# Step 2: create/update your local asf-site branch from the upstream staging
branch
+git branch --track --force asf-site upstream/asf-staging
+
+# Step 3: push it
+# run next command with --dry-run first to see what it will do without making
changes
+git push upstream asf-site:asf-site
+```
+
+Note that Step 3 should always be a fast-forward merge. That is, there should
+never be any reason to force-push it if everything is done correctly. If extra
+commits are ever added to `asf-site` that are not present in `asf-staging`,
+then those branches will need to be sync'd back up in order to continue
+avoiding force pushes.
+
+The final site can be viewed [here][production].
- cp ./_devtools/git-hooks/post-commit .git/hooks/
-[Jekyll]: https://jekyllrb.com/
[Bundler]: https://bundler.io/
+[Jekyll]: https://jekyllrb.com/
+[Liquid]: https://jekyllrb.com/docs/liquid/
+[kramdown]: https://kramdown.gettalong.org/
+[production]: https://accumulo.apache.org
+[staging]: https://accumulo.staged.apache.org
diff --git a/_devtools/git-hooks/post-commit b/_devtools/git-hooks/post-commit
deleted file mode 100755
index 0fb93c5..0000000
--- a/_devtools/git-hooks/post-commit
+++ /dev/null
@@ -1,57 +0,0 @@
-#! /usr/bin/env bash
-
-build_jekyll_site() {
- # $1 is the expected source branch
- local source_br; source_br=$1
- # $2 is the name of the target branch
- local tgt_br; tgt_br=$2
-
- local cur_branch; cur_branch=$(git rev-parse --symbolic-full-name HEAD) ||
return 1
-
- # skip execution on other branches
- [[ $cur_branch == "refs/heads/$source_br" ]] || return 0
-
- # create message
- local message; message="Jekyll build from $source_br:$(git rev-parse
--verify 'HEAD^{commit}' | cut -c1-7)"$'\n'$'\n'"$(git cat-file commit HEAD |
sed '1,/^$/d')"
-
- # import git utils: needed for die, require_clean_work_tree
- . "$(git --exec-path)/git-sh-setup" || return 1
-
- # ensure target branch exists
- local not_a_branch_msg; not_a_branch_msg="$tgt_br is not a branch; this
script can only update branches named $tgt_br (try: git checkout -t
origin/$tgt_br)"
- local target_branch; target_branch=$(git rev-parse --symbolic-full-name
"$tgt_br" 2>/dev/null) || die "fatal: $not_a_branch_msg"
- case "$target_branch" in
- refs/heads/*)
- true
- ;;
- *)
- die "fatal: $not_a_branch_msg"
- ;;
- esac
-
- # don't build what's not checked in
- require_clean_work_tree
-
- # check gem versions
- bundle check >/dev/null || die "fatal: gems are out of date; run 'bundle
install'"
-
- # prep the working location
- local workdir; workdir=$(mktemp -d /tmp/jekyll-XXXXXXXXXX) || die "fatal:
unable to allocate a temporary directory"
- trap "rm -rf '""$workdir""'" 0 1 2 3 15
-
- # actually generate the site
- bundle exec jekyll build --destination "$workdir/_site" || die "fatal:
jekyll build failure"
-
- # prepare and commit to the target branch
- export GIT_INDEX_FILE="$workdir/index"
- rm -f "$workdir/_site/Gemfile" "$workdir/_site/Gemfile.lock"
- git --work-tree="$workdir/_site" add . || die "fatal: error adding
$workdir/_site"
- local tree; tree=$(git write-tree) || die "fatal: error writing tree"
- local commit; commit=$(git commit-tree "$tree" -p "$target_branch" -m
"$message") || die "fatal: error writing commit"
- git update-ref -m "$message" "$target_branch" "$commit" || die "fatal: error
updating ref"
-
- return 0
-}
-
-build_jekyll_site 'master' 'asf-site'
-rm -rf .jekyll-cache/
