|
| 1 | +Contributing to UNICEF Inventory theme |
| 2 | +====================================== |
| 3 | + |
| 4 | +<!-- |
| 5 | + Style rule: One sentence per line please! |
| 6 | + This makes git diffs easier to read in Pull/Merge Requests. |
| 7 | +--> |
| 8 | + |
| 9 | +Thanks for your interest in contributing to the UNICEF Inventory theme! |
| 10 | +The UNICEF Inventory theme is a [Hugo](https://gohugo.io) theme to create a lightweight knowledgebase site. |
| 11 | +This page is a guide for making successful contributions to the project. |
| 12 | + |
| 13 | +**Table of contents**: |
| 14 | + |
| 15 | +1. [Contribution process](#process) |
| 16 | +1. [Conventions & courtesies](#conventions) |
| 17 | + 1. [Start working on an issue](#conventions--issue-start) |
| 18 | + 1. [Inactive issues](#conventions--issue-inactive) |
| 19 | + 1. [Submit a pull request](#conventions--submit-pr) |
| 20 | + 1. [Maintainer response time](#conventions--maintainer-response) |
| 21 | +1. [Structure & components](#components) |
| 22 | + 1. [Theme](#components-theme) |
| 23 | + 1. [Example site](#components-example) |
| 24 | +1. [How to create a development environment](#dev-env) |
| 25 | + 1. [Requirements](#dev-env--requirements) |
| 26 | + 1. [Set up the environment](#dev-env--setup) |
| 27 | + 1. [Run the Hugo server](#dev-env--run-hugo) |
| 28 | + |
| 29 | + |
| 30 | +## <a id="process"></a>Contribution process |
| 31 | + |
| 32 | +The UNICEF Inventory theme is managed as a tool of the [UNICEF Venture Fund](https://www.unicefinnovationfund.org/) within the [UNICEF Office of Innovation](https://www.unicef.org/innovation/). |
| 33 | +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. |
| 34 | +Decisions about the project are generally headed up by a specific tech lead assigned to the project. |
| 35 | +**As of 2022, this is currently [Justin W. Flory](https://github.com/jwflory).** |
| 36 | + |
| 37 | +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. |
| 38 | + |
| 39 | + |
| 40 | +## <a id="conventions"></a>Conventions & courtesies |
| 41 | + |
| 42 | +This section describes conventions and common courtesies when working on the project. |
| 43 | +Following these steps improves the probability of your change or contribution being accepted. |
| 44 | + |
| 45 | +### <a id="conventions--issue-start"></a>Start working on an issue |
| 46 | + |
| 47 | +Want to work on a new issue? |
| 48 | +Follow these steps: |
| 49 | + |
| 50 | +1. Check if issue is already assigned |
| 51 | +1. Leave a comment in the issue to work on it |
| 52 | +1. Start a new git feature branch |
| 53 | + |
| 54 | +If someone else is already assigned, it means the task is **already in progress**. |
| 55 | +An assigned issue is not available to start new work. |
| 56 | +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. |
| 57 | + |
| 58 | +Then, **leave a comment** in the issue you want to work on. |
| 59 | +A maintainer will reply asking for more information or they will assign the issue to you. |
| 60 | +When you are assigned an issue, this means you are approved to work on it. |
| 61 | + |
| 62 | +Finally, once approved to work on an issue, **create a new [git feature branch](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow)** for the issue you are working on. |
| 63 | +This will help you [make a pull request](#conventions--submit-pr) and make revisions easier. |
| 64 | + |
| 65 | +### <a id="conventions--issue-inactive"></a>Inactive issues |
| 66 | + |
| 67 | +Sometimes, an assignee of an issue may no longer have time to work on an issue. |
| 68 | +**After five days of no updates, an issue can be reassigned by a project maintainer.** |
| 69 | +This _DOES NOT_ mean all issues must be solved in five days. |
| 70 | +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. |
| 71 | +This helps to keep issues open and available for those who have time to work on them. |
| 72 | + |
| 73 | +If you are working on an issue and more than five days have passed since your last comment, please give an update when possible. |
| 74 | + |
| 75 | +### <a id="conventions--submit-pr"></a>Submit a pull request |
| 76 | + |
| 77 | +These guidelines help maintainers review new pull requests. |
| 78 | +Stick to the guidelines for faster pull request reviews. |
| 79 | + |
| 80 | +1. Prefer gradual small changes than sudden big changes. |
| 81 | +1. Write meaningful commit messages. |
| 82 | + Commit messages should be clear and brief. |
| 83 | + Tag an issue in your commit message if you are assigned an issue, e.g. `Fixes #123.` |
| 84 | +1. Write a helpful title for your pull request (if someone reads only one sentence, will they understand your change?) |
| 85 | +1. Address the following questions in your pull request: |
| 86 | + 1. What is a summary of your change? |
| 87 | + 1. Why is this change helpful? |
| 88 | + 1. Any specific details to consider? |
| 89 | + 1. What do you think is the outcome of this change? |
| 90 | +1. Include screenshots of before/after if your change is a front-end change. |
| 91 | + |
| 92 | +### <a id="conventions--maintainer-response"></a>Maintainer response time |
| 93 | + |
| 94 | +Project maintainers / mentors are committed to **no more than three days for a reply** during Outreachy rounds. |
| 95 | +If more than three days have passed and you have not received a reply, follow up in [our Matrix room](https://matrix.to/#/#unicef-innovation:matrix.org). |
| 96 | +Someone may have missed your comment. |
| 97 | + |
| 98 | +_Remember_, using issue templates and answering the above questions in pull requests reduces response time from a maintainer to your issue / Pull Request. |
| 99 | + |
| 100 | + |
| 101 | +## <a id="components"></a>Structure & components |
| 102 | + |
| 103 | +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). |
| 104 | + |
| 105 | +### <a id="components-theme"></a>Theme |
| 106 | + |
| 107 | +The website theme that provides the interface and UX of the public website is the [UNICEF Inventory theme](https://github.com/unicef/inventory-hugo-theme). |
| 108 | +It is a theme made for the [Hugo static site generator](https://gohugo.io/). |
| 109 | +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](https://github.com/unicef/inventory-hugo-theme/issues) of the UNICEF Inventory theme. |
| 110 | + |
| 111 | +The content you find published in the [public website](https://sustainers.github.io/design) is hosted here. |
| 112 | +You can find all the content in the [`content/` directory](/content/) of this repository. |
| 113 | +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. |
| 114 | + |
| 115 | +### <a id="components-example"></a>Example site |
| 116 | + |
| 117 | +There is also an example site included in the theme. |
| 118 | +It demonstrates basic features and look-and-feel of the theme. |
| 119 | +You can find the example site in the [`exampleSite/` directory](/exampleSite/) of this repository. |
| 120 | +This example site also acts as the documentation for the Hugo theme as well. |
| 121 | + |
| 122 | + |
| 123 | +## <a id="dev-env"></a>How to create a development environment |
| 124 | + |
| 125 | +So, you want to work on the UNICEF Inventory theme? |
| 126 | +Great! |
| 127 | +This section describes how to set up a development environment using Hugo. |
| 128 | +A development environment is needed to test changes and build the site locally. |
| 129 | +While it is helpful for reviewing changes, it is not required so long as the continuous integration pipeline is passing on a Pull Request. |
| 130 | + |
| 131 | +### <a id="dev-env--requirements"></a>Requirements |
| 132 | + |
| 133 | +To create a developer environment, you must install the following: |
| 134 | + |
| 135 | +* [Hugo](https://gohugo.io/getting-started/installing/) |
| 136 | +* [git](https://github.com/git-guides/install-git) or a git client |
| 137 | + |
| 138 | +### <a id="dev-env--setup"></a>Set up the environment |
| 139 | + |
| 140 | +First, create a fork of the repository to your GitHub account. |
| 141 | +Clone the git repository for **your fork** of the UNICEF Inventory theme: |
| 142 | + |
| 143 | +```sh |
| 144 | +git clone [email protected]:your-username-here/inventory-hugo-theme.git |
| 145 | +``` |
| 146 | + |
| 147 | +### <a id="dev-env--run-hugo"></a>Run the Hugo server |
| 148 | + |
| 149 | +Finally, you will use Hugo to run a local HTTP web server and generate a preview of the site from your own machine. |
| 150 | +You must start the Hugo server from the directory containing the example site. |
| 151 | +Simply change directories to the example site, and run the Hugo server: |
| 152 | + |
| 153 | +```sh |
| 154 | +cd /path/to/repo/ |
| 155 | +cd exampleSite/ |
| 156 | +hugo serve |
| 157 | +``` |
| 158 | + |
| 159 | +The terminal will print a message with a URL to the local preview, such as [localhost:1313/inventory-hugo-theme/](http://localhost:1313/inventory-hugo-theme/). |
| 160 | +Direct your browser to the local preview, and it should appear just as it does on the public website. |
0 commit comments