Skip to content

Latest commit

 

History

History
160 lines (113 loc) · 7.99 KB

CONTRIBUTING.md

File metadata and controls

160 lines (113 loc) · 7.99 KB
Raw

Contributing to UNICEF Inventory theme

Thanks for your interest in contributing to the UNICEF Inventory theme! The UNICEF Inventory theme is a Hugo theme to create a lightweight knowledgebase site. This page is a guide for making successful contributions to the project.

Table of contents:

  1. Contribution process
  2. Conventions & courtesies
    1. Start working on an issue
    2. Inactive issues
    3. Submit a pull request
    4. Maintainer response time
  3. Structure & components
    1. Theme
    2. Example site
  4. How to create a development environment
    1. Requirements
    2. Set up the environment
    3. Run the Hugo server

Contribution process

The UNICEF Inventory theme is managed as a tool of the UNICEF Venture Fund within the UNICEF Office of Innovation. New contributions to the UNICEF Inventory theme are reviewed and managed by the UNICEF Ventures folks responsible for working with our team's open source technology. Decisions about the project are generally headed up by a specific tech lead assigned to the project. As of 2022, this is currently Justin W. Flory.

Since the team is small and our efforts are still early, this project's governance is fluid and may change over time to help us grow and scale, as needed.

Conventions & courtesies

This section describes conventions and common courtesies when working on the project. Following these steps improves the probability of your change or contribution being accepted.

Start working on an issue

Want to work on a new issue? Follow these steps:

  1. Check if issue is already assigned
  2. Leave a comment in the issue to work on it
  3. Start a new git feature branch

If someone else is already assigned, it means the task is already in progress. An assigned issue is not available to start new work. If an issue has no updates for longer than seven days, you may follow up and ask if the assignee is still working on the issue.

Then, leave a comment in the issue you want to work on. A maintainer will reply asking for more information or they will assign the issue to you. When you are assigned an issue, this means you are approved to work on it.

Finally, once approved to work on an issue, create a new git feature branch for the issue you are working on. This will help you make a pull request and make revisions easier.

Inactive issues

Sometimes, an assignee of an issue may no longer have time to work on an issue. After five days of no updates, an issue can be reassigned by a project maintainer. This DOES NOT mean all issues must be solved in five days. It DOES mean if an assignee does not respond to new comments in an issue after five days of their last comment, it can be re-assigned by a maintainer. This helps to keep issues open and available for those who have time to work on them.

If you are working on an issue and more than five days have passed since your last comment, please give an update when possible.

Submit a pull request

These guidelines help maintainers review new pull requests. Stick to the guidelines for faster pull request reviews.

  1. Prefer gradual small changes than sudden big changes.
  2. Write meaningful commit messages. Commit messages should be clear and brief. Tag an issue in your commit message if you are assigned an issue, e.g. Fixes #123.
  3. Write a helpful title for your pull request (if someone reads only one sentence, will they understand your change?)
  4. Address the following questions in your pull request:
    1. What is a summary of your change?
    2. Why is this change helpful?
    3. Any specific details to consider?
    4. What do you think is the outcome of this change?
  5. Include screenshots of before/after if your change is a front-end change.

Maintainer response time

Project maintainers / mentors are committed to no more than three days for a reply during Outreachy rounds. If more than three days have passed and you have not received a reply, follow up in our Matrix room. Someone may have missed your comment.

Remember, using issue templates and answering the above questions in pull requests reduces response time from a maintainer to your issue / Pull Request.

Structure & components

The UNICEF Inventory theme includes two components: the theme and an example site (used as a proof-of-concept to demonstrate capabilities of the theme).

Theme

The website theme that provides the interface and UX of the public website is the UNICEF Inventory theme. It is a theme made for the Hugo static site generator. For changes to the site look-and-feel, user interface, and user experience, you can open bug reports, feature requests, and ideas in the issue tracker of the UNICEF Inventory theme.

The content you find published in the public website is hosted here. You can find all the content in the content/ directory of this repository. For changes to content, categories, and the text published on the website, this repository is the place to have discussions, submit changes, and collaborate with the Design & UX Working Group.

Example site

There is also an example site included in the theme. It demonstrates basic features and look-and-feel of the theme. You can find the example site in the exampleSite/ directory of this repository. This example site also acts as the documentation for the Hugo theme as well.

How to create a development environment

So, you want to work on the UNICEF Inventory theme? Great! This section describes how to set up a development environment using Hugo. A development environment is needed to test changes and build the site locally. While it is helpful for reviewing changes, it is not required so long as the continuous integration pipeline is passing on a Pull Request.

Requirements

To create a developer environment, you must install the following:

Set up the environment

First, create a fork of the repository to your GitHub account. Clone the git repository for your fork of the UNICEF Inventory theme:

git clone [email protected]:your-username-here/inventory-hugo-theme.git

Run the Hugo server

Finally, you will use Hugo to run a local HTTP web server and generate a preview of the site from your own machine. You must start the Hugo server from the directory containing the example site. Simply change directories to the example site, and run the Hugo server:

cd /path/to/repo/
cd exampleSite/
hugo serve

The terminal will print a message with a URL to the local preview, such as localhost:1313/inventory-hugo-theme/. Direct your browser to the local preview, and it should appear just as it does on the public website.