Skip to content

Commit 0eff89c

Browse files
kgodeykgodey
committed
Added GitHub repo guidelines page and split up Contributing Code page.
1 parent 7fbcffd commit 0eff89c

File tree

5 files changed

+182
-35
lines changed

5 files changed

+182
-35
lines changed

‎content/contributing-code/contents.lr

+6-31
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@ title: Contributing Code
66
---
77
body:
88

9-
We do all of our development on GitHub and are generally open to pull requests and proposals for new community-maintained projects. We would especially like help with reviving projects that CC's engineering team does not have the time to actively work on (such as [our WordPress plugin](https://github.com/creativecommons/creativecommons-wordpress-plugin) and [license chooser widget](https://github.com/creativecommons/cc-license-chooser)). We're also looking to improve our documentation and increase our automated test coverage across pretty much all our projects, so help with that would be greatly appreciated.
9+
We do all of our development on GitHub and are generally open to pull requests and proposals for new community-maintained projects.
1010

11-
If you are not familiar with GitHub, [here is an excellent guide to get started](https://guides.github.com/activities/hello-world/).
11+
We would especially like help with reviving projects that CC's engineering team does not have the time to actively work on (such as [our WordPress plugin](https://github.com/creativecommons/creativecommons-wordpress-plugin) and [license chooser widget](https://github.com/creativecommons/cc-license-chooser)). We're also looking to improve our documentation and increase our automated test coverage across pretty much all our projects, so help with that would be greatly appreciated.
12+
13+
Please follow our [pull request guidelines](/contributing-code/pr-guidelines) when submitting code. If you are not familiar with GitHub or pull requests, [here is an excellent guide to get started](https://guides.github.com/activities/hello-world/).
1214

1315
## Working on an existing project
1416

@@ -31,10 +33,10 @@ Once you have identified an issue you'd like to work on, follow these steps:
3133

3234
1. Comment on it and say you'd like to work on that issue.
3335
2. Wait for someone to confirm that you may work on the issue before writing any code. The person who confirms will add an "in progress" label to the issue to indicate that the issue has been assigned.
34-
3. Once the issue has been updated to "in progress", write your code and submit your pull request (be sure to read and follow the **[Pull request guidelines](#pull-request-guidelines)** guide below!)
36+
3. Once the issue has been updated to "in progress", write your code and submit your pull request (be sure to read and follow our **[pull request guidelines](/contributing-code/pr-guidelines)**!)
3537
4. Wait for code review and address any issues raised as soon as you can.
3638

37-
Even if you're not done with the issue, create a [draft pull request](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests) and push your code [early and often](https://www.worklytics.co/blog/commit-early-push-often/). If we haven't heard from you in over a week and someone else expresses interest in that issue, we may assign it to the new person.
39+
Even if you're not done with the issue, create a [draft pull request](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests) and push your code [early and often](https://www.worklytics.co/blog/commit-early-push-often/). If we haven't heard from you in over a week and someone else expresses interest in that issue, we may approve work by the new person.
3840

3941
### Proposing a new issue
4042

@@ -44,33 +46,6 @@ If the project has a roadmap documented in the README, checking the roadmap to s
4446

4547
When in doubt, ask a question on [one of our community forums](/community).
4648

47-
## Pull request guidelines
48-
49-
We aim to review pull requests within three business days.<a href="#footnote-1"><strong>*</strong></a>. If it has been over three business days and you have not received any feedback, feel free to follow up.
50-
51-
* Read and follow the contributing guidelines and code of conduct for the project. Here are screenshots of where to find them for [first time contributors](first-time-contributor-resources.png) and [previous contributors](previous-contributor-resources.png).
52-
* Use the format specified in pull request template for the repository if one exists.
53-
* Describe your change in detail. Too much detail is better than too little.
54-
* Describe how you tested your change.
55-
* If a reviewer is not assigned automatically, manually [request a review](https://help.github.com/en/articles/requesting-a-pull-request-review) from either the repository maintainer (if you have that information) or `@creativecommons/engineering`.
56-
57-
### Code guidelines
58-
59-
* Write comprehensive and robust tests that cover the changes you've made in your work.
60-
* Follow the appropriate code style standards for the language and framework you're using (e.g. PEP 8 for Python).
61-
* Write readable code – keep functions small and modular and name variables descriptively.
62-
* Document your code thoroughly.
63-
* Make sure all the existing tests pass.
64-
* User-facing code should support the following browsers:
65-
* Chrome (Webkit-Blink / 22+)
66-
* Firefox (Gecko / 28+)
67-
* Edge (Chromium based / 12+)
68-
* Opera (Chromium-Blink / 12.1+)
69-
* Safari (Apple’s Webkit / 7+)
70-
* IE 11 (Trident)
71-
72-
<a name="footnote-1"><p class="muted small"><strong>*</strong> CC staff work Monday through Friday and are not available on weekends and national holidays (the specific holidays observed vary based on the person's location). CC is closed between Christmas Eve and New Years' Day every year and for a few days following the CC Global Summit. Also, our availability during events such as the CC Global Summit and our biannual staff meetups is limited.</p></a>
73-
7449
## New projects
7550

7651
We are also open to working on or hosting projects that are related to the Creative Commons licenses or general mission. Our [Google Summer of Code project ideas](/gsoc-2019/project-ideas) list is a good place to find ideas we'd like implemented. If you're interested in working on one of them, please propose it in one of our [community forums](/community) (you don't need to be a student, anyone is welcome to work on those ideas) and work out implementation details with CC staff members before you write any code. If you want to suggest a new project idea, follow the same process.

‎content/contributing-code/github-repo-guidelines/contents.lr

+126
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
_model: page
2+
---
3+
_template: page-with-toc.html
4+
---
5+
title: GitHub Repo Guidelines
6+
---
7+
body:
8+
9+
This is a checklist for all public repositories hosted on the [Creative Commons GitHub organization](https://github.com/creativecommons). Not all repositories meet these criteria yet. Please notify us if a project you'd like to work on does not meet this checklist by opening a GitHub issue associated with the repository.
10+
11+
## Required Items
12+
All GitHub repositories should have the following items to be considered fully ready for external contributors.
13+
14+
### Files
15+
- `/.github/CODEOWNERS`: Defined code owners
16+
- [About code owners - GitHub Help](https://help.github.com/en/articles/about-code-owners)
17+
- `/.cc-metadata.yml`: The standard [CC metadata YAML file](#cc-metadata-file).
18+
- `/CODE_OF_CONDUCT.md`: Code of Conduct
19+
- Feel free to use our standard [`CODE_OF_CONDUCT.md`](https://github.com/creativecommons/.github/blob/master/CODE_OF_CONDUCT.md) file from [creativecommons/.github](https://github.com/creativecommons/.github)
20+
- [Adding a code of conduct to your project - GitHub Help](https://help.github.com/en/articles/adding-a-code-of-conduct-to-your-project)
21+
- `/LICENSE`: license file.
22+
- `/CONTRIBUTING.md`: contributor guidelines
23+
- Can be project-specific or our standard [`CONTRIBUTING.md`](https://github.com/creativecommons/.github/blob/master/CONTRIBUTING.md) file from [creativecommons/.github](https://github.com/creativecommons/.github)
24+
- [Setting guidelines for repository contributors - GitHub Help](https://help.github.com/en/articles/setting-guidelines-for-repository-contributors)
25+
- `/README.md`: read me information file
26+
- Must documents how to install and build the project locally and documents a high level overview of the project and code structure. It should also link to any other available documentation.
27+
- **All pull request templates must include the full text of the [DCO](https://developercertificate.org/)**.
28+
29+
### Additional Items
30+
- CI and code style linters that run automatically whenever new code is pushed (if applicable to the project).
31+
- At least a couple of automated tests (if applicable to the project).
32+
33+
## Optional items
34+
35+
- [Issue templates](https://help.github.com/en/articles/creating-issue-templates-for-your-repository). GitHub pulls the default templates from our [`.github` repository](https://github.com/creativecommons/.github) automatically, but if you want/need to customize them, create them in your repository.
36+
- A [pull request template](https://help.github.com/en/articles/creating-a-pull-request-template-for-your-repository). GitHub pulls the default template from our [`.github` repository](https://github.com/creativecommons/.github) automatically, but if you want/need to customize it, create it in your repository.
37+
- [Support resources](https://help.github.com/en/articles/adding-support-resources-to-your-project). GitHub pulls the default `SUPPORT.md` file from our [`.github` repository](https://github.com/creativecommons/.github) automatically, but if you want/need to customize it, create it in your repository.
38+
- Setting up [branch protections](https://help.github.com/en/articles/about-protected-branches) that don't allow code to be merged in without tests passing or requires reviews for pull requests to be merged.
39+
40+
## Standard Labels
41+
All repositories must contain the following labels. CC staff have access to a script that you can run to make sure all repositories have this label.
42+
43+
Repositories may contain additional custom labels as well. It is recommended that custom labels be explained in the contribution guidelines for that project.
44+
45+
<table class="table table-striped table-sm">
46+
<thead>
47+
<tr>
48+
<th>Name</th>
49+
<th>Color</th>
50+
<th>Description</th>
51+
</tr>
52+
</thead>
53+
<tbody>
54+
<tr>
55+
<td>bug</td>
56+
<td><code>#d73a4a</code></td>
57+
<td>Something isn't working</td>
58+
</tr>
59+
<tr>
60+
<td>duplicate</td>
61+
<td><code>#cfd3d7</code></td>
62+
<td>This issue or pull request already exists</td>
63+
</tr>
64+
<tr>
65+
<td>enhancement</td>
66+
<td><code>#a2eeef</code></td>
67+
<td>New feature or request</td>
68+
</tr>
69+
<tr>
70+
<td>good first issue</td>
71+
<td><code>#7057ff</code></td>
72+
<td>Good for newcomers</td>
73+
</tr>
74+
<tr>
75+
<td>help wanted</td>
76+
<td><code>#008672</code></td>
77+
<td>Seeking help from community</td>
78+
</tr>
79+
<tr>
80+
<td>in progress</td>
81+
<td><code>#ffcc00</code></td>
82+
<td>Currently being worked on</td>
83+
</tr>
84+
<tr>
85+
<td>invalid</td>
86+
<td><code>#e4e669</code></td>
87+
<td>This doesn't seem right</td>
88+
</tr>
89+
<tr>
90+
<td>question</td>
91+
<td><code>#d876e3</code></td>
92+
<td>Further information is requested</td>
93+
</tr>
94+
<tr>
95+
<td>urgent</td>
96+
<td><code>#d93f0b</code></td>
97+
<td>Needs to be fixed ASAP</td>
98+
</tr>
99+
<tr>
100+
<td>wontfix</td>
101+
<td><code>#ffffff</code></td>
102+
<td>This will not be worked on</td>
103+
</tr>
104+
</tbody>
105+
</table>
106+
107+
## CC Metadata file
108+
109+
Each repo should have a `.cc-metadata.yml` file in the root directory with the following structure:
110+
111+
<pre>
112+
<code>
113+
# Whether this GitHub repo is engineering related
114+
engineering_project: true
115+
# Name of the repository/project in English
116+
english_name: CC Catalog API
117+
# All technologies used
118+
technologies: Python, Django, Django REST Framework, Elasticsearch
119+
# Whether this repository should be featured on the CC Open Source site
120+
featured: true
121+
</code>
122+
</pre>
123+
124+
This metadata file is used in the [Projects](/projects) page. Repos that are marked as non-engineering projects are not displayed in the page and repos marked as featured as displayed at the top of the page. Repos should be marked as featured if we are actively looking for community contributions and have the bandwidth to review them quickly.
125+
126+
Repos without this metadata file are treated as `engineering_projects: true` and `featured: false`. A default is necessary since it will take time for us to clean up and add metadata to all our repos.

‎content/contributing-code/pr-guidelines/contents.lr

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
_model: page
2+
---
3+
_template: page.html
4+
---
5+
title: Pull Request Guidelines
6+
---
7+
body:
8+
9+
We ask that contributors to CC projects submit a pull request with your changes. If you're not familiar with pull requests, please read [this GitHub documentation](https://help.github.com/en/articles/about-pull-requests). Here are our expectations for pull requests; following them will expedite the process of merging your code in.
10+
11+
* Read and follow the contributing guidelines and code of conduct for the project. Here are screenshots of where to find them for [first time contributors](first-time-contributor-resources.png) and [previous contributors](previous-contributor-resources.png).
12+
* Use the format specified in pull request template for the repository.
13+
* Describe your change in detail. Too much detail is better than too little.
14+
* Describe how you tested your change.
15+
* If a reviewer is not assigned automatically, manually [request a review](https://help.github.com/en/articles/requesting-a-pull-request-review) from either the repository maintainer (if you have that information) or `@creativecommons/engineering`.
16+
17+
## Code guidelines
18+
19+
* Write comprehensive and robust tests that cover the changes you've made in your work.
20+
* Follow the appropriate code style standards for the language and framework you're using (e.g. PEP 8 for Python).
21+
* Write readable code – keep functions small and modular and name variables descriptively.
22+
* Document your code thoroughly.
23+
* Make sure all the existing tests pass.
24+
* User-facing code should support the following browsers:
25+
* Chrome (Webkit-Blink / 22+)
26+
* Firefox (Gecko / 28+)
27+
* Edge (Chromium based / 12+)
28+
* Opera (Chromium-Blink / 12.1+)
29+
* Safari (Apple’s Webkit / 7+)
30+
* IE 11 (Trident)
31+
32+
We aim to review pull requests within three business days.<a href="#footnote-1"><strong>*</strong></a>. If it has been over three business days and you have not received any feedback, feel free to follow up with us.
33+
34+
<a name="footnote-1"><p class="muted small"><strong>*</strong> CC staff work Monday through Friday and are not available on weekends and national holidays (the specific holidays observed vary based on the person's location). CC is closed between Christmas Eve and New Years' Day every year and for a few days following the CC Global Summit. Also, our availability during events such as the CC Global Summit and our biannual staff meetups is limited.</p></a>

‎templates/layout.html

+15-3
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,22 @@
2929

3030
<div class="collapse navbar-collapse" id="navbarSupportedContent">
3131
<ul class="navbar-nav">
32-
<li class="nav-item{% if this._path == '/' %} active{% endif
33-
%}"><a class="nav-link" href="{{ '/'|url }}">Home</a></li>
32+
<li class="nav-item{% if this._path == '/' %} active{% endif%}">
33+
<a class="nav-link" href="{{ '/'|url }}">Home</a>
34+
</li>
35+
<li class="nav-item dropdown {% if this.is_child_of('/contributing-code') %} active{% endif%}">
36+
<a class="nav-link" href="#" id="navbarContributingCodeDropdown" role="button">Contributing Code</a>
37+
<div class="dropdown-menu" aria-labelledby="navbarContributingCodeDropdown">
38+
{% for href, title in [
39+
['/contributing-code', 'Overview'],
40+
['/contributing-code/pr-guidelines', 'Pull Request Guidelines'],
41+
['/contributing-code/github-repo-guidelines', 'GitHub Repo Guidelines'],
42+
] %}
43+
<a class="dropdown-item" href="{{ href|url }}">{{ title }}</a>
44+
{% endfor %}
45+
</div>
46+
</li>
3447
{% for href, title in [
35-
['/contributing-code', 'Contributing Code'],
3648
['/projects', 'Projects'],
3749
['/blog', 'Blog']
3850
] %}

‎webpack/sass/main.scss

+1-1
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ h2 {
112112

113113
.dropdown-item {
114114
font-size: 1.2em;
115-
text-align: center;
115+
text-align: left;
116116
}
117117

118118
.dropdown:hover {

0 commit comments

Comments
 (0)