From 50f8ead56a54576c18908f836cce857c3a499ee1 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Thu, 27 Sep 2018 10:16:25 +1000 Subject: [PATCH] Remove DocToc frontmatter from published pages - Also fix some markdown syntax. --- doc/development/contributing/design.md | 53 ++++++++---------- doc/development/contributing/index.md | 39 +------------- .../contributing/issue_workflow.md | 54 ++++++------------- .../contributing/merge_request_workflow.md | 17 ++---- 4 files changed, 41 insertions(+), 122 deletions(-) diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 45fe8c26591..be7891061f9 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -1,13 +1,4 @@ - - -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Implement design & UI elements](#implement-design--ui-elements) -- [Style guides](#style-guides) - - - -## Implement design & UI elements +# Implement design & UI elements For guidance on UX implementation at GitLab, please refer to our [Design System](https://design.gitlab.com/). @@ -34,27 +25,27 @@ In order to complete a product discovery issue in a release, you must complete t ## Style guides -1. [Ruby](https://github.com/bbatsov/ruby-style-guide). - Important sections include [Source Code Layout][rss-source] and - [Naming][rss-naming]. Use: - - multi-line method chaining style **Option A**: dot `.` on the second line - - string literal quoting style **Option A**: single quoted by default -1. [Rails](https://github.com/bbatsov/rails-style-guide) -1. [Newlines styleguide][newlines-styleguide] -1. [Testing][testing] -1. [JavaScript styleguide][js-styleguide] -1. [SCSS styleguide][scss-styleguide] -1. [Shell commands](../shell_commands.md) created by GitLab - contributors to enhance security -1. [Database Migrations](../migration_style_guide.md) -1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) -1. [Documentation styleguide](https://docs.gitlab.com/ee/development/documentation/styleguide.html) -1. Interface text should be written subjectively instead of objectively. It - should be the GitLab core team addressing a person. It should be written in - present time and never use past tense (has been/was). For example instead - of _prohibited this user from being saved due to the following errors:_ the - text should be _sorry, we could not create your account because:_ -1. Code should be written in [US English][us-english] +1. [Ruby](https://github.com/bbatsov/ruby-style-guide). + Important sections include [Source Code Layout][rss-source] and + [Naming][rss-naming]. Use: + - multi-line method chaining style **Option A**: dot `.` on the second line + - string literal quoting style **Option A**: single quoted by default +1. [Rails](https://github.com/bbatsov/rails-style-guide) +1. [Newlines styleguide][newlines-styleguide] +1. [Testing][testing] +1. [JavaScript styleguide][js-styleguide] +1. [SCSS styleguide][scss-styleguide] +1. [Shell commands](../shell_commands.md) created by GitLab + contributors to enhance security +1. [Database Migrations](../migration_style_guide.md) +1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) +1. [Documentation styleguide](https://docs.gitlab.com/ee/development/documentation/styleguide.html) +1. Interface text should be written subjectively instead of objectively. It + should be the GitLab core team addressing a person. It should be written in + present time and never use past tense (has been/was). For example instead + of _prohibited this user from being saved due to the following errors:_ the + text should be _sorry, we could not create your account because:_ +1. Code should be written in [US English][us-english] This is also the style used by linting tools such as [RuboCop](https://github.com/bbatsov/rubocop), diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index eac7cb44c40..f4486ae3549 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -1,41 +1,4 @@ - - -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Contribute to GitLab](#contribute-to-gitlab) -- [Security vulnerability disclosure](#security-vulnerability-disclosure) -- [Code of conduct](#code-of-conduct) -- [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) -- [Contribution Flow](#contribution-flow) -- [Workflow labels](#workflow-labels) - - [Type labels](#type-labels) - - [Subject labels](#subject-labels) - - [Team labels](#team-labels) - - [Milestone labels](#milestone-labels) - - [Bug Priority labels](#bug-priority-labels) - - [Bug Severity labels](#bug-severity-labels) - - [Severity impact guidance](#severity-impact-guidance) - - [Label for community contributors](#label-for-community-contributors) -- [Implement design & UI elements](#implement-design--ui-elements) -- [Issue tracker](#issue-tracker) - - [Issue triaging](#issue-triaging) - - [Feature proposals](#feature-proposals) - - [Issue tracker guidelines](#issue-tracker-guidelines) - - [Issue weight](#issue-weight) - - [Regression issues](#regression-issues) - - [Technical and UX debt](#technical-and-ux-debt) - - [Stewardship](#stewardship) -- [Merge requests](#merge-requests) - - [Merge request guidelines](#merge-request-guidelines) - - [Contribution acceptance criteria](#contribution-acceptance-criteria) -- [Definition of done](#definition-of-done) -- [Style guides](#style-guides) - - - -## Contribute to GitLab +# Contribute to GitLab For a first-time step-by-step guide to the contribution process, see ["Contributing to GitLab"](https://about.gitlab.com/contributing/). diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index edd2d063458..7ba8e3dce95 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -1,27 +1,4 @@ - - -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Workflow labels](#workflow-labels) - - [Type labels](#type-labels) - - [Subject labels](#subject-labels) - - [Team labels](#team-labels) - - [Release Scoping labels](#release-scoping-labels) - - [Priority labels](#priority-labels) - - [Severity labels](#severity-labels) - - [Severity impact guidance](#severity-impact-guidance) - - [Label for community contributors](#label-for-community-contributors) - - [Issue triaging](#issue-triaging) - - [Feature proposals](#feature-proposals) - - [Issue tracker guidelines](#issue-tracker-guidelines) - - [Issue weight](#issue-weight) - - [Regression issues](#regression-issues) - - [Technical and UX debt](#technical-and-ux-debt) - - [Stewardship](#stewardship) - - - -## Workflow labels +# Workflow labels To allow for asynchronous issue handling, we use [milestones][milestones-page] and [labels][labels-page]. Leads and product managers handle most of the @@ -45,7 +22,7 @@ labels, you can _always_ add the team and type, and often also the subject. [milestones-page]: https://gitlab.com/gitlab-org/gitlab-ce/milestones [labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels -### Type labels +## Type labels Type labels are very important. They define what kind of issue this is. Every issue should have one or more. @@ -61,7 +38,7 @@ already reserved for subject labels). The descriptions on the [labels page][labels-page] explain what falls under each type label. -### Subject labels +## Subject labels Subject labels are labels that define what area or feature of GitLab this issue hits. They are not always necessary, but very convenient. @@ -75,7 +52,7 @@ issue is labeled with a subject label corresponding to your expertise. Subject labels are always all-lowercase. -### Team labels +## Team labels Team labels specify what team is responsible for this issue. Assigning a team label makes sure issues get the attention of the appropriate @@ -107,7 +84,7 @@ indicate if an issue needs backend work, frontend work, or both. Team labels are always capitalized so that they show up as the first label for any issue. -### Release Scoping labels +## Release Scoping labels Release Scoping labels help us clearly communicate expectations of the work for the release. There are three levels of Release Scoping labels: @@ -138,7 +115,7 @@ This label documents the planned timeline & urgency which is used to measure aga | ~P3 | Medium Priority | Within the next 3 releases (approx one quarter) | | ~P4 | Low Priority | Anything outside the next 3 releases (approx beyond one quarter) | -### Severity labels +## Severity labels Severity labels help us clearly communicate the impact of a ~bug on users. @@ -149,7 +126,7 @@ Severity labels help us clearly communicate the impact of a ~bug on users. | ~S3 | Major Severity | Broken Feature, workaround acceptable | Can create merge requests only from the Merge Requests page, not through the Issue. | | ~S4 | Low Severity | Functionality inconvenience or cosmetic issue | Label colors are incorrect / not being displayed. | -#### Severity impact guidance +### Severity impact guidance Severity levels can be applied further depending on the facet of the impact; e.g. Affected customers, GitLab.com availability, performance and etc. The below is a guideline. @@ -160,7 +137,7 @@ Severity levels can be applied further depending on the facet of the impact; e.g | ~S3 | A few users or a single paid customer affected | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future | | ~S4 | No paid users/customer affected, or expected to in the near future | Minor impact on on GitLab.com | Degradation _may_ occur but it's not likely | -### Label for community contributors +## Label for community contributors Issues that are beneficial to our users, 'nice to haves', that we currently do not have the capacity for or want to give the priority to, are labeled as @@ -210,8 +187,7 @@ any potential community contributor to @-mention per above. [up-for-grabs]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=Accepting+Merge+Requests&scope=all&sort=weight_asc&state=opened [firt-timers]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name%5B%5D=Accepting+Merge+Requests&scope=all&sort=upvotes_desc&state=opened&weight=1 - -### Issue triaging +## Issue triaging Our issue triage policies are [described in our handbook]. You are very welcome to help the GitLab team triage issues. We also organize [issue bash events] once @@ -233,7 +209,7 @@ project. [scheduled pipeline]: https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit [quality/triage-ops]: https://gitlab.com/gitlab-org/quality/triage-ops -### Feature proposals +## Feature proposals To create a feature proposal for CE, open an issue on the [issue tracker of CE][ce-tracker]. @@ -259,7 +235,7 @@ need to ask one of the [core team] members to add the label, if you do not have If you want to create something yourself, consider opening an issue first to discuss whether it is interesting to include this in GitLab. -### Issue tracker guidelines +## Issue tracker guidelines **[Search the issue tracker][ce-tracker]** for similar entries before submitting your own, there's a good chance somebody else had the same issue or @@ -271,7 +247,7 @@ The text in the parenthesis is there to help you with what to include. Omit it when submitting the actual issue. You can copy-paste it and then edit as you see fit. -### Issue weight +## Issue weight Issue weight allows us to get an idea of the amount of work required to solve one or multiple issues. This makes it possible to schedule work more accurately. @@ -293,7 +269,7 @@ is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. issues or chunks. You can simply not set the weight of a parent issue and set weights to children issues. -### Regression issues +## Regression issues Every monthly release has a corresponding issue on the CE issue tracker to keep track of functionality broken by that release and any fixes that need to be @@ -313,7 +289,7 @@ addressed. [8.3 Regressions]: https://gitlab.com/gitlab-org/gitlab-ce/issues/4127 [update the notes]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/pro-tips.md#update-the-regression-issue -### Technical and UX debt +## Technical and UX debt In order to track things that can be improved in GitLab's codebase, we use the ~"technical debt" label in [GitLab's issue tracker][ce-tracker]. @@ -337,7 +313,7 @@ for a release by the appropriate person. Make sure to mention the merge request that the ~"technical debt" issue or ~"UX debt" issue is associated with in the description of the issue. -### Stewardship +## Stewardship For issues related to the open source stewardship of GitLab, there is the ~"stewardship" label. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 685287f7a0c..a286e74908c 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -1,15 +1,4 @@ - - -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Merge requests](#merge-requests) - - [Merge request guidelines](#merge-request-guidelines) - - [Contribution acceptance criteria](#contribution-acceptance-criteria) -- [Definition of done](#definition-of-done) - - - -## Merge requests +# Merge requests We welcome merge requests with fixes and improvements to GitLab code, tests, and/or documentation. The issues that are specifically suitable for @@ -36,7 +25,7 @@ some potentially easy issues. To start with GitLab development download the [GitLab Development Kit][gdk] and see the [Development section](../README.md) for some guidelines. -### Merge request guidelines +## Merge request guidelines If you can, please submit a merge request with the fix or improvements including tests. If you don't know how to fix the issue but can write a test @@ -114,7 +103,7 @@ Please ensure that your merge request meets the contribution acceptance criteria When having your code reviewed and when reviewing merge requests please take the [code review guidelines](../code_review.md) into account. -### Contribution acceptance criteria +## Contribution acceptance criteria 1. The change is as small as possible 1. Include proper tests and make all tests pass (unless it contains a test