Merge branch 'master' into Issue

Zeeshan-2k1 · web-flow · commit 933fa468bb82 · 2020-09-10T11:02:11.000+05:30
diff --git a/content/contributing-code/contents.lr b/content/contributing-code/contents.lr
@@ -13,31 +13,40 @@ body:
 
 Here's a list of [all our current projects](/projects/). We use GitHub issues associated with each project to track the work associated with that project. That's where you can find things to work on.
 
-We make extensive use of issue labels to desginate the status of various issues. We have a standard set of labels across all projects, [documented here](https://github.com/creativecommons/ccos-scripts/blob/master/normalize_repos/labels.py). Here are some of the ones that are most relevant to finding a good issue to work on:
-
-* **Issues tagged `help wanted` or `good first issue`** are available for community contribution**
-    * These issues are available for community contribution and you do not need our permission to work on one of these.
-    * You may work on an issue labeled `good first issue` even if it's not your first issue.
-    * Check the issue comments/labels to see whether someone else has indicated that they are working on it. If someone is already working on it and there has been activity within the last 7 days, you may want to find a different issue to work on.
-* **Issues tagged with one of these labels: `blocked`, `not ready for work`, `ticket work required`, `CC staff only` are not available to the community. Do not work on these.**
-    * Issues tagged `blocked` are blocked by other work that needs to be done first.
-    * Issues tagged `not ready for work` or `ticket work required` need additional work done on the issue before they can be opened to community contributors.
-    * Issues tagged `CC staff only` are not suitable for community contribution, usually because it requires infrastructure access or institutional knowledge that would be impractical to provide to the community.
-* **Issues without any of the above labels _may_ be open for contribution.**
-    * Please add a comment to ask whether the issue is available before starting work.
+We make extensive use of issue labels to designate the priority, status and beginner-friendliness of various issues. We have a standard set of labels across all projects, [documented here](/contributing-code/repo-labels/). Here are some of the ones that are most relevant to finding a good issue to work on:
+
+- **Issues available for community contribution:**
+  - The following tags mark issues that are open for community contribution:
+    - `help wanted`: Open to participation from the community but not necessarily beginner-friendly
+    - `good first issue`: Open to participation from the community and friendly towards new contributors
+  - You do not need our permission to work on one of these issues.
+  - You may work on an issue labeled `good first issue` even if it's not your first issue.
+* **Issues not available for community contribution:**
+  - The following tags mark issues that are _not_ open for community contribution:
+    - `🔒 staff only`: Requires infrastructure access or institutional knowledge that would be impractical to provide to the community
+  - Do not work on these.
+- **Issues not ready for work:**
+  - The following tags mark issues that are _not_ open for community contribution:
+    - `🚧 blocked`: Blocked by other work that needs to be done first
+    - `🧹 ticket work required`: Needs additional work before it is ready to be taken up
+    - `🚦 awaiting triage`: Has not been triaged by a maintainer
+  - Do not work on these.
+- **Issues without any of the above labels:**
+  - These issues _may_ (or may not) be open for contribution.
+  - Please add a comment asking one of the maintainers to triage the issue and label it as appropriate.
 
 Some helpful saved searches on GitHub than can assist with finding an issue:
-- [issues labeled "good first issue"](https://github.com/search?q=org%3Acreativecommons+is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [issues labeled "help wanted"](https://github.com/search?q=org%3Acreativecommons+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
-- [issues labeled "help wanted", and not labeled as "in progress"](https://github.com/search?q=org%3Acreativecommons+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+-label%3A%22in+progress%22)
-- [incomplete pull requests labeled "help wanted"](https://github.com/search?q=org%3Acreativecommons+is%3Apr+is%3Aopen+label%3A%22help+wanted%22)
+- [issues labeled "good first issue"](https://github.com/search?q=org%3Acreativecommons+is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+-linked%3Apr)
+- [issues labeled "help wanted"](https://github.com/search?q=org%3Acreativecommons+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+-linked%3Apr)
+- [PRs labeled "help wanted"](https://github.com/search?q=org%3Acreativecommons+is%3Apr+is%3Aopen+label%3A%22help+wanted%22)
+
+Check the issue comments/labels to see whether someone else has indicated that they are working on it. If someone is already working on it and there has been activity within the last 7 days, you may want to find a different issue to work on.
 
 ## Contribution process
 
 Once you've found an issue you'd like to work on, please follow these steps to make your contribution:
 
 1. Comment on it and say you're working on that issue. This is to avoid conflicts with others also working on the issue.
-    * A project maintainer may mark the issue with an `in progress` label at this point, but we don't always get around to that.
 2. Write your code and submit your pull request. Be sure to read and follow our **[pull request guidelines](/contributing-code/pr-guidelines/)**!
 3. Wait for code review and address any issues raised as soon as you can.
 
diff --git a/content/contributing-code/github-repo-guidelines/contents.lr b/content/contributing-code/github-repo-guidelines/contents.lr
@@ -38,7 +38,7 @@ All GitHub repositories should have the following items to be considered fully r
 
 ## Standard Labels
 
-All repositories must contain a set of standard labels, [listed here](https://github.com/creativecommons/ccos-scripts/blob/master/normalize_repos/labels.json), in addition to repository-specific skill labels, [listed here](https://github.com/creativecommons/ccos-scripts/blob/master/normalize_repos/skills.json).
+All repositories must contain a set of standard labels, [documented here](/contributing-code/repo-labels/), which comprise of common labels in addition to repository-specific skill labels.
 You don't have to set these up manually. The labels are [automatically managed](https://github.com/creativecommons/ccos-scripts/tree/master/normalize_repos) on all CC repositories, and so, must not be renamed.
 
 Repositories may contain additional custom labels as well which will remain unaffected by the sync. It is recommended that custom labels be explained in the contribution guidelines for that project.
diff --git a/content/contributing-code/repo-labels/contents.lr b/content/contributing-code/repo-labels/contents.lr
@@ -0,0 +1,233 @@
+_model: page
+---
+_template: page-with-toc.html
+---
+title: Repository Labels
+---
+description: To facilitate the community in finding ways to contribute that match their experiences and skillsets, we have developed a comprehensive system for labelling issues and PRs. This is an introduction to this standard labelling scheme. 
+---
+body:
+
+Labels consist of three fields, viz. name, description and color. Label names 
+should have a consistent format to aid both filtering within the github UI as 
+well as scanning visually through the list. The following format is the most 
+suited to this task (where `⎵` denotes a single space):
+
+```
+<emoji>⎵<category>:⎵<name>
+```
+
+Even label names with more than two words in the text should be separated by a
+single space `⎵`.
+
+## List of labels
+
+An issue has many different attributes:
+- Priority
+- Status
+- Goal
+- Aspect
+- Skill
+- Talk
+- Friendliness
+
+### *Priority
+
+<div class="table-container">
+  <table class="table is-bordered" style="table-layout: fixed;">
+  <thead>
+    <tr>
+      <td colspan="5"><strong>Priority color chart</strong></td>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td class="has-text-white" style="background-color: #b60205;">Unfavourable</td>
+      <td class="has-text-black" style="background-color: #ff9f1c;">Negative</td>
+      <td class="has-text-black" style="background-color: #ffcc00;">Neutral</td>
+      <td class="has-text-black" style="background-color: #cfda2c;">Positive</td>
+      <td class="has-text-white" style="background-color: #008672;">Favourable</td>
+    </tr>
+    <tr>
+      <td class="has-text-white" style="background-color: #b60205;">#b60205</td>
+      <td class="has-text-black" style="background-color: #ff9f1c;">#ff9f1c</td>
+      <td class="has-text-black" style="background-color: #ffcc00;">#ffcc00</td>
+      <td class="has-text-black" style="background-color: #cfda2c;">#cfda2c</td>
+      <td class="has-text-white" style="background-color: #008672;">#008672</td>
+    </tr>
+  </tbody>
+  </table>
+</div>
+
+The priority of an issue is based on its impact, derived from a combination of 
+urgency and importance. This determines the importance of the issue when sprint 
+planning or deciding which issues to tackle next.
+
+- <span class="gh-label has-text-white" style="background-color: #b60205;">
+    🟥 priority: critical
+  </span>
+  - **Description:** Must be fixed ASAP
+- <span class="gh-label has-text-black" style="background-color: #ff9f1c;">
+    🟧 priority: high
+  </span>
+  - **Description:** Stalls work on the project or its dependents
+- <span class="gh-label has-text-black" style="background-color: #ffcc00;">
+    🟨 priority: medium
+  </span>
+  - **Description:** Not blocking but should be fixed soon
+- <span class="gh-label has-text-black" style="background-color: #cfda2c;">
+    🟩 priority: low
+  </span>
+  - **Description:** Low priority and doesn't need to be rushed
+
+### *Status
+
+<div class="table-container">
+  <table class="table is-bordered" style="table-layout: fixed;">
+  <thead>
+    <tr>
+      <td colspan="5"><strong>Status color chart</strong></td>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td class="has-text-black" style="background-color: #eeeeee;">Lighter</td>
+      <td class="has-text-black" style="background-color: #cccccc;">Light</td>
+      <td class="has-text-black" style="background-color: #999999;">Medium</td>
+      <td class="has-text-white" style="background-color: #666666;">Dark</td>
+      <td class="has-text-white" style="background-color: #333333;">Darker</td>
+    </tr>
+    <tr>
+      <td class="has-text-black" style="background-color: #eeeeee;">#eeeeee</td>
+      <td class="has-text-black" style="background-color: #cccccc;">#cccccc</td>
+      <td class="has-text-black" style="background-color: #999999;">#999999</td>
+      <td class="has-text-white" style="background-color: #666666;">#666666</td>
+      <td class="has-text-white" style="background-color: #333333;">#333333</td>
+    </tr>
+  </tbody>
+  </table>
+</div>
+
+The status of the issue determines whether it is ready for work or not. Issues
+may not be ready to be worked on for a number of reasons and the maintainers
+must keep updating the labels as the situation evolves.
+
+An issue, at the time of closing can have either the 
+<span class="gh-label has-text-black" style="background-color: #cccccc;">
+  🏁 status: ready for dev
+</span>
+or the 
+<span class="gh-label has-text-black" style="background-color: #eeeeee;">
+  ⛔️ status: discarded
+</span>
+label based on whether it was closed with or without resolution, respectively.
+
+- <span class="gh-label has-text-black" style="background-color: #cccccc;">
+    🏁 status: ready for dev
+  </span>
+  - **Description:** Ready for work
+- <span class="gh-label has-text-black" style="background-color: #999999;">
+    🚧 status: blocked
+  </span>
+  - **Description:** Blocked & therefore, not ready for work
+- <span class="gh-label has-text-white" style="background-color: #666666;">
+    🧹 status: ticket work required
+  </span>
+  - **Description:** Needs more details before it can be worked on
+- <span class="gh-label has-text-black" style="background-color: #eeeeee;">
+    ⛔️ status: discarded
+  </span>
+  - **Description:** Will not be worked on
+- <span class="gh-label has-text-white" style="background-color: #333333;">
+    🚦 status: awaiting triage
+  </span>
+  - **Description:** Has not been triaged & therefore, not ready for work
+
+### *Goal
+
+The goal of an issue is the end-result achieved when the issue is resolved. This
+represents the impact of the issue on the scope of the software.
+
+- <span class="gh-label goal">⭐ goal: addition</span>
+  - **Description:** Addition of new feature
+- <span class="gh-label goal">✨ goal: improvement</span>
+  - **Description:** Improvement to an existing feature
+- <span class="gh-label goal">🛠 goal: fix</span>
+  - **Description:** Bug fix
+
+### *Aspect
+
+The aspect of an issue is the side of the project that the issue deals with. A
+single codebase can have multiple aspects to it and knowing which ones will be
+touched helps contributors find relevant issues.
+
+- <span class="gh-label aspect">📄 aspect: text</span>
+  - **Description:** Concerns the textual material in the repository
+- <span class="gh-label aspect">💻 aspect: code</span>
+  - **Description:** Concerns the software code in the repository
+- <span class="gh-label aspect">🕹 aspect: interface</span>
+  - **Description:** Concerns end-users' experience with the software
+- <span class="gh-label aspect">🤖 aspect: dx</span>
+  - **Description:** Concerns developers' experience with the codebase
+
+### Skill
+
+The technical skills a person is required to possess to work on the issue. 
+Skills are a special type of label that vary by repository. Issues may not have
+a skill tag if no special skills are required.
+
+- <span class="gh-label skill">💪 skill: &lt;skill name&gt;</span>
+  - **Description:** Requires proficiency in '&lt;skill name&gt;'
+
+### Talk
+
+Issues with interaction labels do not entail any work to be done on the
+repository. They are for Q&A, RFCs and any other form of discussions. While both
+of these may appear to be too similar, triage permissions are granted to
+collaborators who might not have the answers to questions but by labelling them
+as such, they might draw a faster response from an experienced contributor who
+does. _In the future this category might be rendered redundant by GitHub 
+Discussions and will be removed._
+
+- <span class="gh-label talk">❓ talk: question</span>
+  - **Description:** Can be resolved with an answer
+- <span class="gh-label talk">💬 talk: discussion</span>
+  - **Description:** Open for discussions and feedback
+
+### Friendliness
+
+The level of friendliness a particular issue is the valency of the issue 
+towards contributions from the community. Some issues provide a great 
+introduction while others require a little more familiarity with the codebase.
+_These issues do not have the category prefix as two of them are special labels
+recognized by GitHub. The special ones don't have emojis either._
+
+- <span class="gh-label friendliness">good first issue</span>
+  - **Description:** New-contributor friendly
+- <span class="gh-label friendliness">help wanted</span>
+  - **Description:** Open to participation from the community
+- <span class="gh-label friendliness">🔒 staff only</span>
+  - **Description:** Restricted to CC staff members
+
+### Miscellaneous
+
+- <span class="gh-label has-background-black has-text-white">
+    🤯 ノಠ益ಠノ彡┻━┻
+  </span>
+  - **Description:** Aaargh!
+  
+## Usage rules
+
+In the above categories, some are marked with an `*` sign. Those are mandatory
+categories and every issue is required to have at least one label from those
+categories.
+
+Only issues labelled with 
+<span class="gh-label has-text-white" style="background-color: #333333;">
+  🚦 status: awaiting triage
+</span>
+are allowed to not have all mandatory labels (seeing as they have not been
+triaged yet).
+
+Categories not marked with an `*` are optional and it is upto the discretion of
+the maintainers to have apply labels from those categories to issues. 
diff --git a/databags/repos.json b/databags/repos.json
@@ -83,6 +83,17 @@
             "url": "https://github.com/creativecommons/cc-licenses",
             "website": null
         },
+        {
+            "created": "2020-09-08T19:18:51",
+            "description": "",
+            "id": 293905720,
+            "language": null,
+            "license": null,
+            "name": "cc-licenses-data",
+            "slack": "",
+            "url": "https://github.com/creativecommons/cc-licenses-data",
+            "website": null
+        },
         {
             "created": "2019-06-12T18:15:54",
             "description": "Automated link checker for legalcode and license URLs",
@@ -1038,6 +1049,17 @@
             "url": "https://github.com/creativecommons/wp-theme-creativecommons.org",
             "website": null
         },
+        {
+            "created": "2020-09-08T17:50:40",
+            "description": "[WIP] WordPress theme for openglam.org",
+            "id": 293885986,
+            "language": null,
+            "license": null,
+            "name": "wp-theme-openglam",
+            "slack": "",
+            "url": "https://github.com/creativecommons/wp-theme-openglam",
+            "website": null
+        },
         {
             "created": "2019-10-16T17:42:01",
             "description": "",
diff --git a/themes/vocabulary_theme/templates/layout.html b/themes/vocabulary_theme/templates/layout.html
@@ -76,9 +76,10 @@
             <div class="navbar-dropdown">
               {% for href, title in [
                 ['/contributing-code', 'Contribution Guidelines'],
-                ['/contributing-code/projects', 'Project List'],
                 ['/contributing-code/pr-guidelines', 'Pull Request Guidelines'],
                 ['/contributing-code/github-repo-guidelines', 'GitHub Repo Guidelines'],
+                ['/contributing-code/repo-labels', 'Repository Labels'],
+                ['/contributing-code/projects', 'Project List'],
                 ['/contributing-code/usability', 'Usability'],
               ] %}
                 <a class="navbar-item" href="{{ href|url }}">{{ title }}</a>
diff --git a/themes/vocabulary_theme/templates/page-with-toc.html b/themes/vocabulary_theme/templates/page-with-toc.html
@@ -19,20 +19,17 @@ <h1>{{ this.title }}</h1>
             {% if this.is_child_of('/contributing-code') %}
               <aside class="menu sidebar-menu">
                 <ul class="menu-list">
-                  <li>
-                    <a class="{% if this.path == '/contributing-code/projects' %} is-active {% endif%} link" href="{{ '/contributing-code/projects'|url }}">Project List</a>
-                  </li>
-                  <hr class="divider">
                   <li>
                     <a class="{% if this.path == '/contributing-code' %} is-active {% endif%} link" href="{{ '/contributing-code'|url }}">Contribution Guidelines</a>
                     <ul>
-                      <li><a class="{% if this.path == '/contributing-code/pr-guidelines' %} is-active {% endif%} link" href="{{ '/contributing-code/pr-guidelines'|url }}"><i class="icon circle-filled"></i>PR Guidelines</a></li>
+                      <li><a class="{% if this.path == '/contributing-code/pr-guidelines' %} is-active {% endif%} link" href="{{ '/contributing-code/pr-guidelines'|url }}"><i class="icon circle-filled"></i>Pull Request Guidelines</a></li>
                       <li><a class="{% if this.path == '/contributing-code/github-repo-guidelines' %} is-active {% endif%} link" href="{{ '/contributing-code/github-repo-guidelines'|url }}"><i class="icon circle-filled"></i>Github Repo Guidelines</a></li>
+                      <li><a class="{% if this.path == '/contributing-code/repo-labels' %} is-active {% endif%} link" href="{{ '/contributing-code/repo-labels'|url }}"><i class="icon circle-filled"></i>Repository Labels</a></li>
                     </ul>
                   </li>
                   <hr class="divider">
                   <li>
-                    <a class="link" href="{{ '/contributing-code/cc-search'|url }}">CC Search</a>
+                    <a class="{% if this.path == '/contributing-code/projects' %} is-active {% endif%} link" href="{{ '/contributing-code/projects'|url }}">Project List</a>
                   </li>
                   <hr class="divider">
                   <li>
diff --git a/webpack/sass/main.scss b/webpack/sass/main.scss
@@ -100,6 +100,7 @@ pre {
   }
 }
 
+
 // Sticky utility function
 .sticky-top {
   position: sticky;

Original file line number	Diff line number	Diff line change
`@@ -100,6 +100,7 @@ pre {`
`100`	`100`	`}`
`101`	`101`	`}`
`102`	`102`
	`103`	`+`
`103`	`104`	`// Sticky utility function`
`104`	`105`	`.sticky-top {`
`105`	`106`	`position: sticky;`