Merge branch 'document-design-to-development-process' into 'master'

Add a paragraph on "Implementing design & UI elements" in CONTRIBUTING.md

Closes gitlab-com/www-gitlab-com#544

See merge request !2983

2 files changed, 118 insertions, 50 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b13f36af214..714701e7345 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,24 +3,27 @@
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
 - [Contribute to GitLab](#contribute-to-gitlab)
-  - [Contributor license agreement](#contributor-license-agreement)
-  - [Security vulnerability disclosure](#security-vulnerability-disclosure)
-  - [Closing policy for issues and merge requests](#closing-policy-for-issues-and-merge-requests)
-  - [Helping others](#helping-others)
-  - [I want to contribute!](#i-want-to-contribute)
-  - [Issue tracker](#issue-tracker)
-      - [Feature proposals](#feature-proposals)
-      - [Issue tracker guidelines](#issue-tracker-guidelines)
-      - [Issue weight](#issue-weight)
-      - [Regression issues](#regression-issues)
-  - [Merge requests](#merge-requests)
-      - [Merge request guidelines](#merge-request-guidelines)
-      - [Merge request description format](#merge-request-description-format)
-      - [Contribution acceptance criteria](#contribution-acceptance-criteria)
-  - [Changes for Stable Releases](#changes-for-stable-releases)
-  - [Definition of done](#definition-of-done)
-  - [Style guides](#style-guides)
-  - [Code of conduct](#code-of-conduct)
+    - [Contributor license agreement](#contributor-license-agreement)
+    - [Security vulnerability disclosure](#security-vulnerability-disclosure)
+    - [Closing policy for issues and merge requests](#closing-policy-for-issues-and-merge-requests)
+    - [Helping others](#helping-others)
+    - [I want to contribute!](#i-want-to-contribute)
+    - [Implement design & UI elements](#implement-design-ui-elements)
+        - [Design reference](#design-reference)
+        - [UI development kit](#ui-development-kit)
+    - [Issue tracker](#issue-tracker)
+        - [Feature proposals](#feature-proposals)
+        - [Issue tracker guidelines](#issue-tracker-guidelines)
+        - [Issue weight](#issue-weight)
+        - [Regression issues](#regression-issues)
+    - [Merge requests](#merge-requests)
+        - [Merge request guidelines](#merge-request-guidelines)
+        - [Merge request description format](#merge-request-description-format)
+        - [Contribution acceptance criteria](#contribution-acceptance-criteria)
+    - [Changes for Stable Releases](#changes-for-stable-releases)
+    - [Definition of done](#definition-of-done)
+    - [Style guides](#style-guides)
+    - [Code of conduct](#code-of-conduct)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -83,6 +86,22 @@ GitLab.
 
 This was inspired by [an article by Kent C. Dodds][medium-up-for-grabs].
 
+## Implement design & UI elements
+
+### Design reference
+
+The GitLab design reference can be found in the [gitlab-design] project.
+The designs are made using Antetype (`.atype` files). You can use the
+[free Antetype viewer (Mac OSX only)] or grab an exported PNG from the design
+(the PNG is 1:1).
+
+The current designs can be found in the [`gitlab1.atype` file].
+
+### UI development kit
+
+Implemented UI elements can also be found at https://gitlab.com/help/ui. Please
+note that this page isn't comprehensive at this time.
+
 ## Issue tracker
 
 To get support for your particular problem please use the
@@ -299,13 +318,14 @@ to us than having a minimal commit log. The smaller an MR is the more likely it
 is it will be merged (quickly). After that you can send more MRs to enhance it.
 
 For examples of feedback on merge requests please look at already
-[closed merge requests][closed-merge-requests]. If you would like quick feedback on your merge
-request feel free to mention one of the Merge Marshalls of the [core team][core-team].
+[closed merge requests][closed-merge-requests]. If you would like quick feedback
+on your merge request feel free to mention one of the Merge Marshalls in the
+[core team][core-team] or one of the
+[Merge request coaches](https://about.gitlab.com/team/).
 Please ensure that your merge request meets the contribution acceptance criteria.
 
 When having your code reviewed and when reviewing merge requests please take the
-[thoughtbot code review guidelines](https://github.com/thoughtbot/guides/tree/master/code-review)
-into account.
+[Thoughtbot code review guide] into account.
 
 ### Merge request description format
 
@@ -473,3 +493,7 @@ available at [http://contributor-covenant.org/version/1/1/0/](http://contributor
 [rss-source]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#source-code-layout
 [rss-naming]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#naming
 [doc-styleguide]: doc/development/doc_styleguide.md "Documentation styleguide"
+[gitlab-design]: https://gitlab.com/gitlab-org/gitlab-design
+[free Antetype viewer (Mac OSX only)]: https://itunes.apple.com/us/app/antetype-viewer/id824152298?mt=12
+[`gitlab1.atype` file]: https://gitlab.com/gitlab-org/gitlab-design/tree/master/gitlab1.atype/
+[Thoughtbot code review guide]: https://github.com/thoughtbot/guides/tree/master/code-review
diff --git a/PROCESS.md b/PROCESS.md
index 54ebe11d5a0..07572612543 100644
--- a/PROCESS.md
+++ b/PROCESS.md
@@ -2,23 +2,39 @@
 
 ## Purpose of describing the contributing process
 
-Below we describe the contributing process to GitLab for two reasons. So that contributors know what to expect from maintainers (possible responses, friendly treatment, etc.). And so that maintainers know what to expect from contributors (use the latest version, ensure that the issue is addressed, friendly treatment, etc.).
+Below we describe the contributing process to GitLab for two reasons. So that
+contributors know what to expect from maintainers (possible responses, friendly
+treatment, etc.). And so that maintainers know what to expect from contributors
+(use the latest version, ensure that the issue is addressed, friendly treatment,
+etc.).
 
 ## Common actions
 
 ### Issue team
-- Looks for issues without [workflow labels](#how-we-handle-issues) and triages issue
-- Closes invalid issues with a comment (duplicates, [fixed in newer version](#issue-fixed-in-newer-version), [issue report for old version](#issue-report-for-old-version), not a problem in GitLab, etc.)
-- Asks for feedback from issue reporter ([invalid issue reports](#improperly-formatted-issue), [format code](#code-format), etc.)
-- Monitors all issues for feedback (but especially ones commented on since automatically watching them)
+
+- Looks for issues without [workflow labels](#how-we-handle-issues) and triages
+  issue
+- Closes invalid issues with a comment (duplicates,
+  [fixed in newer version](#issue-fixed-in-newer-version),
+  [issue report for old version](#issue-report-for-old-version), not a problem
+  in GitLab, etc.)
+- Asks for feedback from issue reporter
+  ([invalid issue reports](#improperly-formatted-issue),
+  [format code](#code-format), etc.)
+- Monitors all issues for feedback (but especially ones commented on since
+  automatically watching them)
 - Closes issues with no feedback from the reporter for two weeks
 
-### Merge marshal
+### Merge marshall & merge request coach
 
-- Responds to merge requests the issue team mentions them in and monitors for new merge requests
-- Provides feedback to the merge request submitter to improve the merge request (style, tests, etc.)
-- Mark merge requests 'ready-for-merge' when they meet the contribution guidelines
-- Mention developer(s) based on the [list of members and their specialities](https://about.gitlab.com/core-team/)
+- Responds to merge requests the issue team mentions them in and monitors for
+  new merge requests
+- Provides feedback to the merge request submitter to improve the merge request
+  (style, tests, etc.)
+- Mark merge requests `Ready for Merge` when they meet the
+  [contribution acceptance criteria]
+- Mention developer(s) based on the
+  [list of members and their specialities][team]
 - Closes merge requests with no feedback from the reporter for two weeks
 
 ## Priorities of the issue team
@@ -30,26 +46,40 @@ Below we describe the contributing process to GitLab for two reasons. So that co
 
 ## Mentioning people
 
-The most important thing is making sure valid issues receive feedback from the development team. Therefore the priority is mentioning developers that can help on those issue. Please select someone with relevant experience from [GitLab core team](https://about.gitlab.com/core-team/). If there is nobody mentioned with that expertise look in the commit history for the affected files to find someone. Avoid mentioning the lead developer, this is the person that is least likely to give a timely response. If the involvement of the lead developer is needed the other core team members will mention this person.
+The most important thing is making sure valid issues receive feedback from the
+development team. Therefore the priority is mentioning developers that can help
+on those issue. Please select someone with relevant experience from
+[GitLab core team][core-team]. If there is nobody mentioned with that expertise
+look in the commit history for the affected files to find someone. Avoid
+mentioning the lead developer, this is the person that is least likely to give a
+timely response. If the involvement of the lead developer is needed the other
+core team members will mention this person.
 
 ## Workflow labels
 
-Workflow labels are purposely not very detailed since that would be hard to keep updated as you would need to re-evaluate them after every comment. We optionally use functional labels on demand when want to group related issues to get an overview (for example all issues related to RVM, to tackle them in one go) and to add details to the issue.
+Workflow labels are purposely not very detailed since that would be hard to keep
+updated as you would need to re-evaluate them after every comment. We optionally
+use functional labels on demand when want to group related issues to get an
+overview (for example all issues related to RVM, to tackle them in one go) and
+to add details to the issue.
 
 - ~"Awaiting Feedback" Feedback pending from the reporter
 - ~UX needs help from a UX designer
-- ~Frontend needs help from a Front-end engineer
+- ~Frontend needs help from a Front-end engineer. Please follow the
+  ["Implement design & UI elements" guidelines].
 - ~up-for-grabs is an issue suitable for first-time contributors, of reasonable difficulty and size. Not exclusive with other labels.
 - ~"feature proposal" is a proposal for a new feature for GitLab. People are encouraged to vote
 in support or comment for further detail. Do not use `feature request`.
-- ~bug is an issue reporting undesirable or incorrect behavior. 
+- ~bug is an issue reporting undesirable or incorrect behavior.
 - ~customer is an issue reported by enterprise subscribers. This label should
-be accompanied by *bug* or *feature proposal* labels. 
+be accompanied by *bug* or *feature proposal* labels.
 Example workflow: when a UX designer provided a design but it needs frontend work they remove the UX label and add the frontend label.
 
 ## Functional labels
 
-These labels describe what development specialities are involved such as: PostgreSQL, UX, LDAP.
+These labels describe what development specialities are involved such as: `CI`,
+`Core`, `Documentation`, `Frontend`, `Issues`, `Merge Requests`, `Omnibus`,
+`Release`, `Repository`, `UX`.
 
 ## Assigning issues
 
@@ -57,21 +87,29 @@ If an issue is complex and needs the attention of a specific person, assignment
 
 ## Label colors
 
--   Light orange `#fef2c0`: workflow labels for issue team members (awaiting feedback, awaiting confirmation of fix)
--   Bright orange `#eb6420`: workflow labels for core team members (attached MR, awaiting developer action/feedback)
--   Light blue `#82C5FF`: functional labels
--   Green labels `#009800`: issues that can generally be ignored. For example, issues given the following labels normally can be closed immediately:
-    - Support (see copy & paste response: [Support requests and configuration questions](#support-requests-and-configuration-questions)
+- Light orange `#fef2c0`: workflow labels for issue team members (awaiting
+  feedback, awaiting confirmation of fix)
+- Bright orange `#eb6420`: workflow labels for core team members (attached MR,
+  awaiting developer action/feedback)
+- Light blue `#82C5FF`: functional labels
+- Green labels `#009800`: issues that can generally be ignored. For example,
+  issues given the following labels normally can be closed immediately:
+  - Support (see copy & paste response:
+    [Support requests and configuration questions](#support-requests-and-configuration-questions)
 
 ## Be kind
 
-Be kind to people trying to contribute. Be aware that people may be a non-native English speaker, they might not understand things or they might be very sensitive as to how you word things. Use Emoji to express your feelings (heart, star, smile, etc.). Some good tips about giving feedback to merge requests is in the [Thoughtbot code review guide](https://github.com/thoughtbot/guides/tree/master/code-review).
+Be kind to people trying to contribute. Be aware that people may be a non-native
+English speaker, they might not understand things or they might be very
+sensitive as to how you word things. Use Emoji to express your feelings (heart,
+star, smile, etc.). Some good tips about giving feedback to merge requests is in
+the [Thoughtbot code review guide].
 
 ## Copy & paste responses
 
 ### Improperly formatted issue
 
-Thanks for the issue report. Please reformat your issue to conform to the issue tracker guidelines found in our \[contributing guidelines\]\(https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#issue-tracker-guidelines).
+Thanks for the issue report. Please reformat your issue to conform to the \[contributing guidelines\]\(https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#issue-tracker-guidelines).
 
 ### Issue report for old version
 
@@ -107,11 +145,11 @@ This merge request has been closed because a request for more information has no
 
 ### Accepting merge requests
 
-Is there an issue on the [issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues)
-that is similar to this?
-Could you please link it here?
+Is there an issue on the
+\[issue tracker\]\(https://gitlab.com/gitlab-org/gitlab-ce/issues) that is
+similar to this? Could you please link it here?
 Please be aware that new functionality that is not marked
-[accepting merge requests](https://gitlab.com/gitlab-org/gitlab-ce/issues?milestone_id=&scope=all&sort=created_desc&state=opened&utf8=%E2%9C%93&assignee_id=&author_id=&milestone_title=&label_name=Accepting+Merge+Requests)
+\[accepting merge requests\]\(https://gitlab.com/gitlab-org/gitlab-ce/issues?milestone_id=&scope=all&sort=created_desc&state=opened&utf8=%E2%9C%93&assignee_id=&author_id=&milestone_title=&label_name=Accepting+Merge+Requests)
 might not make it into GitLab.
 
 ### Only accepting merge requests with green tests
@@ -126,4 +164,10 @@ rebase with master to see if that solves the issue.
 We are currently in the process of closing down the issue tracker on GitHub, to
 prevent duplication with the GitLab.com issue tracker.
 Since this is an older issue I'll be closing this for now. If you think this is
-still an issue I encourage you to open it on the \[GitLab.com issue tracker\](https://gitlab.com/gitlab-org/gitlab-ce/issues).
+still an issue I encourage you to open it on the \[GitLab.com issue tracker\]\(https://gitlab.com/gitlab-org/gitlab-ce/issues).
+
+[core-team]: https://about.gitlab.com/core-team/
+[team]: https://about.gitlab.com/team/
+[contribution acceptance criteria]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#contribution-acceptance-criteria
+["Implement design & UI elements" guidelines]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md##implement-design-ui-elements
+[Thoughtbot code review guide]: https://github.com/thoughtbot/guides/tree/master/code-review