Google GSoC guides: the mentor and contributor handbooks, and how the site is built

What the repository actually is

The google/gsocguides repository contains the Google Summer of Code Mentor Guide and Contributor Guide, and the project description says it plainly.

That is worth pausing on, because the name of the repository suggests a programme rather than a product. This is the documentation for how Summer of Code works, kept in the open so that it can be corrected, and the two audiences are separate documents. The mentor guide covers the side of the programme where somebody is supervising a student's project, and the contributor guide covers the side where a student, or a prospective student, is proposing and executing one.

The site is built with Jekyll, and the template and build are based on the documentation-theme-jekyll theme by tomjoht, with the theme's own documentation describing how the site is put together. The published guides live at google.github.io/gsocguides, and the tree shows the standard Jekyll layout: a _config.yml, a _data/ directory for the site's data, an _includes/ and a _layouts/ directory for the templates, a pages/ directory for the actual content, and css/, js/ and images/ for the assets.

There is also a search.json, a sitemap.xml and a feed.xml, which are the files a static site generator emits for search and syndication, and a tooltips.json and a third_party/ directory, which suggests the theme pulls in a few external resources and keeps the configuration for them in the repository rather than in the template.

The licence field is one that GitHub cannot classify, so the terms are in the LICENSE file, and the primary language recorded for the repository is CSS, which is a fair summary of a documentation site where the styling is the code.

Local development, which is a Docker image and a port

The local development section is short, and the reason it is short is that everything happens inside a container.

# Build docker image (once)
make build-image

# Run server (listens on port 4000)
make serve

The Makefile shows what those two targets do. The build-image target is a plain docker build tagged gsocguides:latest, and the serve target runs that image with the current directory mounted at /src and the port published, then overrides the entry point to run Jekyll with the host set to 0.0.0.0 and the port passed explicitly. The volume mount is what makes the server useful, because editing a file on the host is immediately visible in the served site without rebuilding the image.

The Dockerfile is where the dependency set lives. It is based on ruby:3.1, sets the locale environment variables to a UTF-8 configuration, installs nodejs and python3-pygments, copies the Gemfile and Gemfile.lock in first so that the bundle install layer is cached independently of the content, declares a volume at /src, exposes port 4000, and the entry point is the Jekyll server itself.

The compose file describes the same thing as a service, with the build context, the Dockerfile, an image name of result/latest, the port mapping from 4000 to 4000, and the same volume mapping of the current directory to /src.

So the whole contributor workflow is a container that already has the right Ruby, the right gems and the right Node tooling, which sidesteps the usual documentation-site problem where three contributors have three different local setups and one of them is broken.

The renumbering script, and why the order numbers cannot have gaps

The section on adding new pages is the most interesting part of the contributor documentation, because it describes a constraint that looks like a quirk and is actually a design decision.

for i in $(seq 28 -1 15);
    do n=$((i+1));
    fi=$(echo $i-*.md);
    fn=$(echo $fi | sed -e "s/${i}-/${n}-/");
    git mv $fi $fn;
    perl -pi -e "s/^order: $i\$/order: $n/" $fn;
done

# 28 is the current last page.
# 15 is the page to insert before.
# Iterate backwards to ensure there's only one page with each index at a time.

The reason it is needed is given explicitly. It is needed because the pages are named after their order, and because the Next and Prev button requires all the order numbers to be contiguous, and you cannot skip any.

So a contributor adding a page in the middle is not adding a file, they are inserting a page into an ordered sequence where the filename is the position. The script does the renumbering, and the loop runs backwards from the current last page to the insertion point precisely so that there is only ever one page with a given index at a time, which is what makes the git mv steps unambiguous.

The fact that the script also rewrites the order field in the front matter of each moved page, with a perl one-liner anchored to the start of the line, is the detail that makes it work rather than merely look like it works. A renumbering script that moved files but left the metadata behind would produce a site whose navigation silently disagreed with its filenames.

And the comment about the Next and Prev button is the reason to care. The constraint exists because the navigation is generated from a contiguous sequence, and a documentation site where the previous and next links break is a real problem for a project whose whole job is guiding people through a process.

Linting, gem upgrades and the rest of the housekeeping

Two smaller pieces of the contributor documentation are worth reading because they describe the maintenance of the build itself.

The first is the Markdownlint step, which can be run locally:

npm install markdownlint-cli
./node_modules/.bin/markdownlint  pages

The repository carries both a .markdownlint.yaml and a .markdownlint-cli2.yaml, which is the older and the newer configuration file for the same tool, and the Makefile has a lint target that runs npx -y markdownlint-cli2. The help output of the Makefile lists the three commands a contributor is expected to know, build-image, serve and lint.

For a documentation repository, the linter is the automated check. There is no test suite for prose, so the rules about heading levels, list style and link formatting are the whole of the quality gate, and running them locally before pushing is the difference between a clean contribution and a review comment.

The second is the gem upgrade procedure, which is three commands and a warning:

bundle install --path vendor/bundle
bundle update github-pages
rm -rf vendor/bundle

The last line is the one that matters, since the vendor directory is a local install location that is not meant to be committed, and the note that follows says not to forget to rebuild the docker image.

That last note is the kind of thing that causes a confusing afternoon. The gems live in the image, so upgrading them on the host has no effect until the image is rebuilt, and the image is built once by the build-image target. The workflow is therefore a loop: change the Gemfile, rebuild the image, serve, look at the site.

The rest of the tree is the standard Jekyll complement, with a 404.md, an AUTHORS file, a createtag script, a feed.xml, and a CONTRIBUTING.md that the README points to for anyone who wants to contribute.

Where the GSoC guides repository is the wrong tool

The first limit is that this is the process documentation, not the programme's live information. The repository holds the Mentor Guide and the Contributor Guide, and the published site is the reading of those. A student looking for the timeline of the current year, the list of available projects or the application form is looking for a different set of pages, and the guides explain the shape of the process rather than the instance of it.

The second is the age of the toolchain, and it is a choice rather than a bug. The site is a Jekyll site on Ruby 3.1 in a container, with the theme from tomjoht and the github-pages gem that the upgrade procedure bumps. That is a stack that works, and it works because it is pinned and containerised, and a project that has not needed to move off it has not needed to. For a contributor that means the local workflow is one docker command rather than a modern JavaScript toolchain, which is a good trade for a documentation site and a bad one if you want to contribute tooling improvements.

The third is the renumbering constraint, which is the sharpest practical edge in the repository. Inserting a page in the middle means renumbering every page after it, with a script that uses git mv and a perl rewrite, and the file naming convention ties the identity of a page to its position. That is fine for a sequential handbook, and it means a page that is referred to by number in a discussion, or by a link with a number in it, moves when a page is inserted before it. Any external link to a numbered page is a link that can break in a pull request that adds a page earlier in the sequence.

The fourth is that the content is only as good as its last edit. A documentation site with no tests has no way to detect a broken internal link, a stale process step or a section that no longer matches what the programme does, other than a reader noticing. The markdownlint catches formatting and not content, and the guides for a programme whose details change every year are exactly the kind of document where that distinction matters.

And the fifth is the licensing, which for a repository with a documentation licence that GitHub cannot classify is something a redistributor has to read rather than assume. For contributors and readers of the published guides it makes no difference at all, and for anyone planning to fork the material and reuse it, it is the first thing to check.

Editorial conclusion

The GSoC guides repository is worth looking at if you are a Summer of Code mentor or student, because the two handbooks are the actual process documentation for the programme and they are maintained in the open, and because the site is small enough to understand in an afternoon, with a Docker-based preview that avoids installing Ruby locally. It is the wrong tool if you are looking for the current year's schedule rather than the process, and it is the wrong tool if your contribution is a code change rather than a documentation change. Before you start, check three things: that you have Docker, since the documented local workflow is to build an image once and serve it on port 4000 rather than installing Jekyll and the gems yourself; that you read the page renumbering rules, because pages are named after their order and the previous and next navigation requires the order numbers to be contiguous, so inserting a page means renumbering the ones after it with the provided script rather than just adding a file; and that you run the linter, since the repository ships both a markdownlint configuration and a make lint target, and the CI is a documentation site where formatting is the only automated check there is.

Frequently asked questions

Official sources

1. google/gsocguides on GitHub
2. Issues
3. Project website
4. README