-
Notifications
You must be signed in to change notification settings - Fork 2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
🆕 👥 .github: Add contributing guidelines #13
Open
jwflory
wants to merge
1
commit into
main
Choose a base branch
from
add/contrib-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| Contributing to the Sustain OSS Design Inventory | ||
| ================================================ | ||
|
|
||
| Thanks for your interest in working on the Sustain OSS Design Inventory! | ||
| We appreciate your interest and enthusiasm. | ||
| This document explains the contribution process, the different components of the project, and how to create a development environment to work on the site. | ||
|
|
||
|
|
||
| **Table of contents**: | ||
|
|
||
| 1. [Contribution process](#process) | ||
| 1. [Structure and components](#components) | ||
| 1. [How to create a development environment](#dev-env) | ||
|
|
||
|
|
||
| ## <a id="process"></a>Contribution process | ||
|
|
||
| The Sustain OSS Design Inventory is governed by the [Sustain OSS Design & UX Working Group](https://sustainoss.org/working-groups/design-and-ux/). | ||
| The Working Group is part of the [Sustain OSS community](https://sustainoss.org/about/). | ||
| Decisions about the project, the content published herein, and other aspects are generally headed up by these fine folks (in alphabetical order): | ||
|
|
||
| 1. Eriol Fox | ||
| 1. Georgia Bullen | ||
| 1. Justin W. Flory | ||
| 1. Memo Esparza | ||
| 1. Richard Littauer | ||
|
|
||
| Since the team is small and our efforts are still getting started, the governance of this project is fluid and may change over time to help us grow and scale the effort, as needed. | ||
|
|
||
| ### Governance model: Lazy consensus | ||
|
|
||
| When reviewing changes or new ideas to this project, the maintainers will adhere to a **lazy consensus** model of decision-making. | ||
|
|
||
| **What does lazy consensus mean?** | ||
| In order for a change or new effort to move forward, it must receive _at least one_ "+1" vote from a maintainer, and no "-1" votes from any maintainer. | ||
| This enables work to move forward quickly if there are no major disagreements. | ||
| For minor and non-controversial changes, a single approval allows a change to move forward with little resistance. | ||
| If there is a change or new idea a core maintainer raises issue with, the "-1" vote requires the process to pause and have a longer discussion around a change or new idea. | ||
|
|
||
| **What constitutes a vote?** | ||
| In the context of this repository, a vote can mean a review on a Pull Request or a comment on an Issue. | ||
| A maintainer can give a "+1" vote or approve a Pull Request if they agree with the change. | ||
| A maintainer can also abstain on a decision by giving a "+0" vote, which will not give the required approval to make a change but neither will it block the change from moving forward if another maintainer agrees. | ||
| Finally, a maintainer can give a "-1" vote or request changes on a Pull Request if they take issue with a change and wish to either see changes made or have a longer discussion first. | ||
|
|
||
| **How does someone become a core maintainer?** | ||
| It is a good question. | ||
| Our effort is still very new, and we haven't worked out this question yet. | ||
| But if you have thoughts, we'd love to hear them in the `#open-design-discussions` channel in the [Open Collective Slack](https://join.slack.com/t/opencollective/shared_invite/zt-f43qko76-sD8G~e_vQCm4TtpIsM4i~A). | ||
|
|
||
|
|
||
| ## <a id="components"></a>Structure and components | ||
|
|
||
| The Sustain OSS Design Inventory includes two components: the content (hosted in this repository) and the theme (used in building this site, but hosted separately). | ||
|
|
||
| ### Content | ||
|
|
||
| The content you find published in the [public website](https://sustainers.github.io/design) is hosted here. | ||
| You can find all the content in the [`content/` directory](/content/) 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. | ||
|
|
||
| ### Theme | ||
|
|
||
| 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). | ||
| It is a theme made for the [Hugo static site generator](https://gohugo.io/). | ||
| 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. | ||
|
|
||
|
|
||
| ## <a id="dev-env"></a>How to create a development environment | ||
|
|
||
| So, you want to work on the Sustain OSS Design Inventory? | ||
| 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 need to have the following: | ||
|
|
||
| * [Hugo](https://gohugo.io/getting-started/installing/) | ||
| * [git](https://github.com/git-guides/install-git) or a git client | ||
|
|
||
| ### Setting up the environment | ||
|
|
||
| The Design Inventory actually has _two_ git repositories combined into one. | ||
| This is done with [git submodules](). | ||
| To build the site locally, you need to clone the [`sustainoss/design` repo]() with the [`unicef/inventory-hugo-theme` submodule](). | ||
|
|
||
| **First-time clone**: | ||
| If you have not cloned the repo yet, do it with this command: | ||
|
|
||
| ```sh | ||
| git clone --recurse-submodules [email protected]:sustainers/design.git | ||
| ``` | ||
|
|
||
| **Add the git submodule after cloning**: | ||
| Already cloned the repo, but forgot to clone it with the submodule? | ||
| No worries. | ||
| Follow these steps to add it after. | ||
|
|
||
| ```sh | ||
| cd /path/to/repo/ | ||
| git submodule update --init | ||
| ``` | ||
|
|
||
| ### 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. | ||
| Simply change directories to the repository, and run the Hugo server: | ||
|
|
||
| ```sh | ||
| cd /path/to/repo/ | ||
| hugo serve | ||
| ``` | ||
|
|
||
| The terminal will print a message with a URL to the local preview, such as [localhost:1313/design/](http://localhost:1313/design/). | ||
| Direct your browser to the local preview, and it should appear just as it does on the public website. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think this is our current process. Perhaps something like: "A maintainer can give a general approval by saying something like "+1" or "LGTM", or just approve a PR using GitHub's review feature." Otherwise, this seems dogmatic.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@RichardLitt My intent was not to capture our current process (do we have one?). I was setting out to document a norm that we could agree on following as a group. Although I'm not sure I see the difference between what I've written here and your proposed edit, unless you are suggesting to strike this entire process?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I hear you. Your proposal gives off the impression that the only way to vote is to say "+1" or "-1", when those are personal language choices. If someone just wrote "I like this", that would also work for our current process, but the writing here is too restrictive for that use-case. I propose we broaden your writing to include language choices.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah! Yeah, that makes sense and it is fair feedback. I can amend this. I'll probably get to this sometime next week and include any other feedback from other reviewers at the same time.