Contributing

Contributing#

The Handbook is modelled after GitLab’s Handbook, which is an important source of their ‘institutional knowledge’ and enabler of their ‘remote-first’ way of working. The main motivations for the handbook, sketched in Fig. 4, are to:

../_images/contributing-motivation.png

Fig. 4 Sketch of the motivating reason for the handbook - toward collaborative knowledge exchange.#

  • Have a common repository of shared knowledge

  • Establish best practices and common processes

  • Reduce knowledge loss from busy or departing colleague

  • Make it easier to take on new projects and change area

  • Get experience writing high quality technical documentation

  • Get experience collaborating on a shared resource

What to Add#

If as part of your work you had to search for something in a Search Engine, ask on an Instant Messenger or email someone - this knowledge is likely going to be useful for others and should be captured here, subject to the caveats below.

Some things to avoid are:

  • sensitive material related to individuals, our partners or their projects

  • binary content - everything should be plain text where possible, Sharepoint is more suitable for binary or interactive collaborative content

  • large sample codes or recipes - they belong in their own repositories, if they are public they can be hyperlinked to from here

  • formal training or National Service related material - this will have its own specific formatting and presentation requirements. Content here can be used to inform, develop or extend training material or user guides

  • opinions or speculation - try to remain factual and descriptive where possible

  • external content without a suitable license and attribution – only add external material that we can share under a CC BY-SA license. Content that we generate ourselves and include will also be placed under this license.

How to Contribute#

../_images/contribution-workflow.png

Fig. 5 Schematic of the basic Handbook contribution workflow.#

Take a look for existing content#

Take a look at the contents chapter to get an overall idea of the book structure. Use the tips in the ‘Navigating’ section to see if the content already exists, and if not where the most suitable place to put it might be.

Add your content#

You can check out a local copy of the repository:

git clone git@git.ichec.ie:handbooks/ichec-handbook.git

and make a branch to add your changes:

git checkout -b my_working_branch

The repo layout is sketched in Fig. 6. To modify an existing page you can find it in the src directory. The page name should look similar to the end of its URL for the HTML version or the Chapter or Section name for the PDF version. You can also refer to the file _toc.yaml in the top-level directory, which contains the overall book structure, following the Jupyter Book specification.

../_images/contributing-repo-layout.png

Fig. 6 Sketch of the repository layout.#

If you want to add a new page you can create a Markdown (.md) file in the src directory and add it to a sensible place in the _toc.yaml.

The book supports MyST Markdown, which is a superset of ‘regular’ Markdown. If you don’t need fancy features like callouts and footnotes you needn’t delve into the details of MyST to get started.

Push your change#

Once you are happy with your change you can push it back to the cloud repository:

git add .
git commit -m "A useful message about my change"
git push origin my_working_branch

You can then open the repository page in Gitlab where you should see a banner to create a ‘Merge Request’.

When you create the Merge Request some automated checks will run. They check for formatting, broken links and that the book can be rebuilt. If they pass you are welcome to merge your change. There is no need to request or wait for a review unless you specifically want feedback. Your Merge Request will also generate PDF and HTML versions of the book - which you can download from the Gitlab Pipeline view and check before merging.

If you run into any problems you can check the ‘Advanced Editing’ section below, or ask for help on Slack.

Advanced Editing#

This section has information and tips for more advanced contributions to the handbook. It may also be useful if you are having problems with automated checks.

Building and Testing Locally#

If you want your own locally built copy of the handbook or are trying to troubleshoot a break in the CI on Gitlab you can do so as follows.

For a simple, minimal build you can create a Python Virtual Environment and install the minimal project dependencies:

python3 -m venv --prompt handbook .venv
source .venv/bin/activate
pip install -r infra/requirements.txt

Then you can run:

jb build --all .

from the project top-level directory, which will use Jupyter Book to build just the HTML documentation. The build output will show you the location of the index.html file, which you can open in your web browser.

To do a full build, matching all CI checks you will need some more system dependencies.

  1. A full LaTeX environment, to allow PDF generation. You can consult the Communications/LaTeX section of the handbook for details on how to do this, however on Mac it amounts to simply installing MacTeX.

  2. Imagemagick and Cairo installations, to allow conversion of image formats between SVG, PNG and PDF. On Mac this is brew install imagemagick cairo.

Then you can run:

icreports book

which will run all CI checks and output PDF and HTML versions of the book.

Adding Images#

You can add images, ideally in plaintext Tikz/Tex or SVG formats or else as small as possible, to the src/media directory. Try to give the image a descriptive name, so others will get an idea of what it is ‘at a glance’.

If you are adding plain-text or vector images (Tikz/SVG) they will be automatically converted to PNG format during the build process. When you are linking to these images from markdown files you should point to /src/media/my_file_name.png rather than /src/media/my_file_name.svg to pick up the converted version. Take a look at the raw Markdown file for Fig. 5 on this page for an example.

You should only add media that we are allowed to redistribute. Creative Commons CC-BY-SA compatibility is required, please see here for details on information needed to include and attribute this material https://wiki.creativecommons.org/wiki/Recommended_practices_for_attribution. If you created the media yourself this shouldn’t need any further action.

Contents