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.
- 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:
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:
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
plugins.md file requires to run the
script. The script depends on the
pygerrit2 library, which can
be installed using the provided
cd homepage pipenv install --dev
plugins.py may require using either one of its
options, depending on CI authentication:
cd homepage pipenv run python tools/plugins.py docker-compose up (browse to) http://localhost:4000/plugins.html
plugins.md file lends the browsed
If changes are made to the
plugins.py script, check for coding errors and
style violations with
flake8, and format the code with
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:
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).
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] ---
- 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:
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:
[permalink]is a descriptive name of the file and
YYYY-MM-DDis 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 ---
[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
_postsdirectory or the
For posts to be published immediately, save the new file in the
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
_draftsdirectory. When the post is complete, move the file into the
Save any images in the top-level
Appendix: Logging in to Firebase
If you have never used Firebase before, you need to perform these steps:
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.
Note: When you initialize Firebase, specify
_siteas 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: