Maintainer's guide for O.S. Inventory

Justin W. Flory
Essential day-to-day admin tasks and maintenance of the UNICEF Open Source Inventory.

This document is a maintainer’s guide for the UNICEF Open Source Inventory. Yes, this very site! This guide covers key information and helpful resources, as well as best practices when maintaining the O.S. Inventory.

1. Contribution conventions 🔗

This section explains contribution conventions for the Open Source Inventory. These are common conventions that all contributors are asked to make when contributing to this repository. Please make a best effort to follow these conventions at all times, unless there is a justified reason to break convention.

1.1. Label conventions 🔗

All issue and pull request labels belong to one of the meta-categories of labels below:

  1. C omponent: Used for indicating what component, or part, of the applications is related. In a large project, there are different kinds of components that exist together in a repository. The UNICEF Open Source Inventory includes content management, front-end code, and back-end code. Usually indicates what kind of maintainer is needed to move forward.

  2. I nclusion: Used for community inclusion topics. Issues or pull requests tagged with inclusion labels typically impact the contribution workflow and other people working on the project.

  3. T ype: What types of issues and pull requests do we get? These labels indicate whether something new is added or if improvements are made to existing components.

  4. X: Used for close statuses. These labels are only used on closed issues and pull requests.

  5. ?: Used for labels that require more information. Usually indicates experienced maintainer action is required to move forward.

1.2. Commit message conventions 🔗

  1. Prefix your commit message with the component you are changing, and optionally, an emoji. If you are editing a page in the Project Management category, start your commit message with Project Management:. If you are changing Hugo configurations, archetypes, or other tweaks, start your commit with message with hugo:. And so on. Optionally, you may add a GitHub emoji to your commit message summary line that best represents your change.

  2. All commit messages on the main branch should be good commit messages.

  3. Avoid merge commits. Preserve good commit messages by rebase merging, or if commit messages are not helpful in aggregate, use squash merging. Do not allow merge commits.

1.3. How to update git submodule as a maintainer 🔗

There are two components to this Hugo website: content repository (unicef/inventory) and theme repository (unicef/inventory-hugo-theme).

The content repository hosts all of the written information published in the O.S. Inventory. The theme repository hosts the front-end design and Hugo templates used in the O.S. Inventory. The content repository clones the theme repository as a git submodule to the themes/inventory/ path. Therefore, whenever changes are made to the upstream theme repository, the git submodule for the theme repository needs to be updated. The git submodule must be updated from the content repository.

1.3.1. Example: git in command line 🔗

The shell commands below were tested with the git command line client, version 2.31 or later:

1
2
3
4
5
6
7

git submodule update --remote --rebase
cd themes/inventory/
git fetch
git checkout <latest commit hash>
cd ../../
git add themes/inventory
git commit --signoff

1.4. How development decisions are prioritized 🔗

Development decisions are prioritized according to the needs of the following stakeholders:

  1. UNICEF Office of Innovation staff and consultants

  2. UNICEF Venture Fund grantees and portfolio companies

  3. UNICEF colleagues

  4. UN colleagues

  5. Open Source practitioners and subject-matter experts (e.g. associated to a private-sector Open Source Program Office)

  6. General public

For as long as this list does not generate conflict, this is sufficient to guide development decisions by meeting the needs of key stakeholders. Over time, if this list creates friction, this part of the maintainer’s guide should be revisited.

2. Common resources and cheat sheets 🔗

This section provides common resources, links, and references for different subject material covered in the project. See the sub-headings below for quick references on any aspect of the UNICEF Open Source Inventory.

2.1. AsciiDoc syntax cheat sheet 🔗

AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text.

— asciidoctor.org
AsciiDoc Syntax Quick Reference

Handy cheat sheet of what the AsciiDoc markup looks like. Use this for quick references and checking up on how to formatting, lists, media content (images and video), table of contents, and more.

AsciiDoc Recommended Practices

Best practices about writing in AsciiDoc. Most importantly, note that every sentence should be on its own line.

2.2. Hugo documentation 🔗

Hugo Documentation

Main landing page for upstream Hugo documentation. This is the first resource to check when exploring more advanced feature development and changes to the site theme.

Hugo Community

Discussion and Q&A forum for upstream Hugo community. Good place to take questions, queries, and doubts about working with Hugo.

GitHub

Upstream GitHub repository for Hugo. Issue tracker is usually responsive. If you hit a bug or something seems wrong, open an issue and seek help from a maintainer after you did your own homework.

2.2.1. Suggested reading 🔗

Not sure where to start? These pages are helpful primers:

  • Archetypes: Archetypes are templates used when creating new content.

  • Front Matter: Hugo allows you to add front matter in yaml, toml, or json to your content files.

  • Templates: Overview of Hugo templating system.

  • Functions: Overview of Go and Hugo functions.

  • Variables and Params: Hugo templates are context-aware and make a large number of values available as you create views for your website.

2.3. CI pipeline (diagram) 🔗

The diagram below explains how the Continuous Integration pipeline is set up to deploy HTML from git to production:

Continuous Integration pipeline workflow. How changes flow from GitHub to production.

Updated on 19 Sep 2022