Publishing Gerrit Documentation | Gerrit Code Review

There is a build job homepage which automatically updates the plugin page, generates the homepage and deploys the new version.

The remainder of this topic describes how to manually publish updates to the Gerrit website.

Prerequisites

Install Docker
Install Docker Compose
Prepare your system to host content on Firebase.
Have the appropriate permissions to the Gerrit Code Review project on the Google Cloud Platform.

Cloning the repository

The repository that contains the Gerrit website is called homepage.

To clone the repository, run the following command.

git clone https://gerrit.googlesource.com/homepage && \
(cd homepage && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \
https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \
chmod +x `git rev-parse --git-dir`/hooks/commit-msg)

Building the site

In these steps, you build the site on your local machine.

The output files for the site are stored in the _site directory. This directory is not stored in the repository.

To build the site:

Navigate to the root of the homepage repository.
Type the following command:
```
 docker-compose up
```

If that command fails, try these, with caution:

 docker-compose down && \
 git clean -fdx && \
 docker-compose up

The docker file is configured to build the site and serve it on a local staging server. To access the staging server, navigate to the following URL in your browser:

http://localhost:4000

To build the site without staging it, type the following command:

docker run -v $(pwd):/site bretfisher/jekyll-serve jekyll build

Updating the plugins page

Updating the plugins.md file requires to run the plugins.py script. The script depends on the pygerrit2 library, which can be installed using the provided pipenv environment:

cd homepage
pipenv install --dev

Running plugins.py may require using either one of its -a or -n options, depending on CI authentication:

cd homepage
pipenv run python tools/plugins.py
docker-compose up
(browse to) http://localhost:4000/plugins.html

The resulting plugins.md file lends the browsed plugins.html page.

If changes are made to the plugins.py script, check for coding errors and style violations with flake8, and format the code with black:

pipenv run flake8 tools/plugins.py
pipenv run black tools/plugins.py

Both of these tools are also provided in the pipenv environment.

Deploying the site

Note: If this is your first time running Firebase on this machine, you need to provide authentication credentials. For more information, see Appendix: Logging in to Firebase.

To deploy the site:

Make sure you have proper ownership of the output files.

 sudo chown -R $( id -u $USER ):$( id -g $USER ) _site/

Type the following command from the root of the repository:
```
 firebase deploy
```

In a few moments, the site is updated. You can view the deployment in the Firebase console.

Rolling back to another deployment

Open the Firebase console.
From the left navigation pane, click Hosting.
In Deployment History, select the deployment you’d like to return to.
Click the More button (three vertical dots).
Select Rollback.

Writing content

This section describes how to add new content to the documentation.

Note: For complete documentation on the site template and how to create content, see Getting started with the Documentation Theme for Jekyll.

Using the text editor of your choice, create an empty document.
At the top of the document, add the following text block:
```
 ---
 title: [TITLE_NAME]
 permalink: [FILENAME]
 ---
```
Where:
- TITLE_NAME is the title of the topic.
- FILENAME is the output name of the file. This name MUST be unique.
Author your topic using the Kramdown Markdown.

Save the file in the following directory:

 path/to/repository/jekyll-source/pages/gerrit

This template supports a few additional extensions for authoring content. Some that you might find useful include:

For more information on how the documentation is structured and the syntax it supports, see the template documentation.

Writing blog posts

The Gerrit website supports adding blog posts. Users can view a list of current blogposts by click the News link in the navigation bar.

To create a blog post:

Create a new markdown file. The name of the file must use this format:
```
 YYYY-MM-DD-[permalink].md
```
Where [permalink] is a descriptive name of the file and YYYY-MM-DD is the date that will be shown on the post. Posts will be listed on the index in chronological order; posts with a date in the future will not be rendered or appear in the index until that date.
Add the following to the top of the blog post:
```
     ---
     title: [TITLE]
     tags: [TAGS]
     keywords: [KEYWORDS]
     permalink: [FILENAME].html
     summary: [SUMMARY]
     hide_sidebar: true
     hide_navtoggle: true
     toc: true
     ---
```
Where:
- [TITLE] is the title of the blog post
- [TAGS] is an optional space-delimited list of tags
- [KEYWORDS] is an optional space-delimited list of keywords
- [FILENAME] is the name of the file
- [SUMMARY] is a one- to two- sentence description of the post
Save the post in the _posts directory or the _drafts directory.

For posts to be published immediately, save the new file in the _posts directory.

For posts that are still work in progress, or to be written iteratively by multiple authors across several commits, save the new file in the _drafts directory. When the post is complete, move the file into the _posts directory.
Save any images in the top-level images directory.

Appendix: Logging in to Firebase

If you have never used Firebase before, you need to perform these steps:

Install the Firebase CLI.
Log in to Firebase.

Note: After you provide your credentials, you are returned to http://localhost to confirm your authentication. If you cannot access localhost for some reason, you can run this command instead: firebase login --no-localhost.
Initialize Firebase.

Note: When you initialize Firebase, specify _site as the root directory. Accept the defaults for all other options.

Appendix: Jekyll Template

Jekyll sites use a variety of templates. For Gerrit, we have selected this template. We chose this template because it has robust support for documentation. For example, this template supports:

A left navigation system that includes sections that can expand and collapse
Support for tabs within content, which makes it easier to display multiple options for users (for instance, displaying GWT or PolyGerrit instructions)
A simple, but extensible Search box

As the theme is already included in the repository for the Gerrit site, you should not need to install it when making changes to your content. However, to learn about the template and its features, use the following link:

http://idratherbewriting.com/documentation-theme-jekyll/