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.
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)
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.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.
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.
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.
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:
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.
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 postSave 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.
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 _site as the root directory. Accept the defaults for all other options.
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: