enhance documentation around contributing to electron (electron#11887)

* add issues document * add documentation coding style to doc * copyediting * replace `nodejs/node` with `electron/electron` * fix commasplice * fix two most important... s/is/are/ * omit unnecessary words * add pull requests doc * copyediting * add general code style to styleguide * updates to CONTRIBUTING.md * copyediting * mark shell blocks as ```sh * mitigate phrase duplication e.g. 'best practice' * lots of opinionated changes to omit unnecessary words * fix numbering & re-apply changes that I overwrote
54J4N · Feb 12, 2018 · 533dfc4 · 533dfc4
1 parent 31e0bc0
commit 533dfc4
Show file tree

Hide file tree

Showing 4 changed files with 397 additions and 62 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,21 +10,15 @@ The following is a set of guidelines for contributing to Electron.
 These are just guidelines, not rules, use your best judgment and feel free to
 propose changes to this document in a pull request.
 
-## Submitting Issues
+## [Issues](https://electronjs.org/docs/development/issues)
 
-### Creating Issues
-* You can create an issue [here](https://github.com/electron/electron/issues/new),
-but before doing that please read the notes below and include as many details as
-possible with your report. If you can, please include:
-  * The version of Electron you are using
-  * The operating system you are using
-  * If applicable, what you were doing when the issue arose and what you
-  expected to happen
-* Other things that will help resolve your issue:
-  * Screenshots and animated GIFs
-  * Error output that appears in your terminal, dev tools or as an alert
-  * Perform a [cursory search](https://github.com/electron/electron/issues?utf8=✓&q=is%3Aissue+)
-  to see if a similar issue has already been submitted
+Issues are created [here](https://github.com/electron/electron/issues/new).
+
+* [How to Contribute in Issues](https://electronjs.org/docs/development/issues#how-to-contribute-in-issues)
+* [Asking for General Help](https://electronjs.org/docs/development/issues#asking-for-general-help)
+* [Submitting a Bug Report](https://electronjs.org/docs/development/issues#submitting-a-bug-report)
+* [Triaging a Bug Report](https://electronjs.org/docs/development/issues#triaging-a-bug-report)
+* [Resolving a Bug Report](https://electronjs.org/docs/development/issues#resolving-a-bug-report)
 
 ### Issue Maintenance and Closure
 * If an issue is inactive for 45 days (no activity of any kind), it will be
@@ -34,56 +28,29 @@ the issue will be closed.
   * If an issue has been closed and you still feel it's relevant, feel free to
   ping a maintainer or add a comment!
 
-## Development
-* Build instructions can be found in [docs/development](docs/development).
-
-## Submitting Pull Requests
-
-* Include screenshots and animated GIFs in your pull request whenever possible.
-* Follow the JavaScript, C++, and Python [coding style defined in docs](/docs/development/coding-style.md).
-* Write documentation in [Markdown](https://daringfireball.net/projects/markdown).
-  See the [Documentation Styleguide](/docs/styleguide.md).
-* Use short, present tense commit messages. See [Commit Message Styleguide](#git-commit-messages).
+## [Pull Requests](https://electronjs.org/docs/development/pull-requests)
 
-## Styleguides
+Pull Requests are the way concrete changes are made to the code, documentation,
+dependencies, and tools contained in the `electron/electron` repository.
 
-### General Code
+* [Setting up your local environment](https://electronjs.org/docs/development/pull-requests#setting-up-your-local-environment)
+  * [Step 1: Fork](https://electronjs.org/docs/development/pull-requests#step-1-fork)
+  * [Step 2: Build](https://electronjs.org/docs/development/pull-requests#step-2-build)
+  * [Step 3: Branch](https://electronjs.org/docs/development/pull-requests#step-3-branch)
+* [The Process of Making Changes](https://electronjs.org/docs/development/pull-requests#the-process-of-making-changes)
+  * [Step 4: Code](https://electronjs.org/docs/development/pull-requests#step-4-code)
+  * [Step 5: Commit](https://electronjs.org/docs/development/pull-requests#step-5-commit)
+    * [Commit message guidelines](https://electronjs.org/docs/development/pull-requests#commit-message-guidelines)
+  * [Step 6: Rebase](https://electronjs.org/docs/development/pull-requests#step-6-rebase)
+  * [Step 7: Test](https://electronjs.org/docs/development/pull-requests#step-7-test)
+  * [Step 8: Push](https://electronjs.org/docs/development/pull-requests#step-8-push)
+  * [Step 8: Opening the Pull Request](https://electronjs.org/docs/development/pull-requests#step-8-opening-the-pull-request)
+  * [Step 9: Discuss and Update](#step-9-discuss-and-update)
+    * [Approval and Request Changes Workflow](https://electronjs.org/docs/development/pull-requests#approval-and-request-changes-workflow)
+  * [Step 10: Landing](https://electronjs.org/docs/development/pull-requests#step-10-landing)
+  * [Continuous Integration Testing](https://electronjs.org/docs/development/pull-requests#continuous-integration-testing)
 
-* End files with a newline.
-* Place requires in the following order:
-  * Built in Node Modules (such as `path`)
-  * Built in Electron Modules (such as `ipc`, `app`)
-  * Local Modules (using relative paths)
-* Place class properties in the following order:
-  * Class methods and properties (methods starting with a `@`)
-  * Instance methods and properties
-* Avoid platform-dependent code:
-  * Use `path.join()` to concatenate filenames.
-  * Use `os.tmpdir()` rather than `/tmp` when you need to reference the
-    temporary directory.
-* Using a plain `return` when returning explicitly at the end of a function.
-  * Not `return null`, `return undefined`, `null`, or `undefined`
+## Style Guides
 
-### Git Commit Messages
+See [Coding Style](https://electronjs.org/docs/development/coding-style) for information about which standards Electron adheres to in different parts of its codebase.
 
-* Use the present tense ("Add feature" not "Added feature")
-* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
-* Limit the first line to 72 characters or less
-* Reference issues and pull requests liberally
-* When only changing documentation, include `[ci skip]` in the commit description
-* Consider starting the commit message with an applicable emoji:
-  * :art: `:art:` when improving the format/structure of the code
-  * :racehorse: `:racehorse:` when improving performance
-  * :non-potable_water: `:non-potable_water:` when plugging memory leaks
-  * :memo: `:memo:` when writing docs
-  * :penguin: `:penguin:` when fixing something on Linux
-  * :apple: `:apple:` when fixing something on macOS
-  * :checkered_flag: `:checkered_flag:` when fixing something on Windows
-  * :bug: `:bug:` when fixing a bug
-  * :fire: `:fire:` when removing code or files
-  * :green_heart: `:green_heart:` when fixing the CI build
-  * :white_check_mark: `:white_check_mark:` when adding tests
-  * :lock: `:lock:` when dealing with security
-  * :arrow_up: `:arrow_up:` when upgrading dependencies
-  * :arrow_down: `:arrow_down:` when downgrading dependencies
-  * :shirt: `:shirt:` when removing linter warnings
diff --git a/docs/development/coding-style.md b/docs/development/coding-style.md
@@ -5,6 +5,23 @@ These are the style guidelines for coding in Electron.
 You can run `npm run lint` to show any style issues detected by `cpplint` and
 `eslint`.
 
+## General Code
+
+* End files with a newline.
+* Place requires in the following order:
+  * Built in Node Modules (such as `path`)
+  * Built in Electron Modules (such as `ipc`, `app`)
+  * Local Modules (using relative paths)
+* Place class properties in the following order:
+  * Class methods and properties (methods starting with a `@`)
+  * Instance methods and properties
+* Avoid platform-dependent code:
+  * Use `path.join()` to concatenate filenames.
+  * Use `os.tmpdir()` rather than `/tmp` when you need to reference the
+    temporary directory.
+* Using a plain `return` when returning explicitly at the end of a function.
+  * Not `return null`, `return undefined`, `null`, or `undefined`
+
 ## C++ and Python
 
 For C++ and Python, we follow Chromium's [Coding
@@ -21,6 +38,13 @@ document. The document mentions some special types, scoped types (that
 automatically release their memory when going out of scope), logging mechanisms
 etc.
 
+## Documentation
+
+* Write [remark](https://github.com/remarkjs/remark) markdown style
+
+You can run `npm run lint-docs` to ensure that your documentation changes are
+formatted correctly.
+
 ## JavaScript
 
 * Write [standard](https://npm.im/standard) JavaScript style.

diff --git a/docs/development/issues.md b/docs/development/issues.md
@@ -0,0 +1,109 @@
+# Issues In Electron
+
+# Issues
+
+* [How to Contribute in Issues](#how-to-contribute-in-issues)
+* [Asking for General Help](#asking-for-general-help)
+* [Submitting a Bug Report](#submitting-a-bug-report)
+* [Triaging a Bug Report](#triaging-a-bug-report)
+* [Resolving a Bug Report](#resolving-a-bug-report)
+
+## How to Contribute in Issues
+
+For any issue, there are fundamentally three ways an individual can
+contribute:
+
+1. By opening the issue for discussion: If you believe that you have found
+   a new bug in Electron, you should report it by creating a new issue in
+   the `electron/electron` issue tracker.
+2. By helping to triage the issue: You can do this either by providing
+   assistive details (a reproducible test case that demonstrates a bug) or by
+   providing suggestions to address the issue.
+3. By helping to resolve the issue: This can be done by demonstrating
+   that the issue is not a bug or is fixed; but more often, by opening
+   a pull request that changes the source in `electron/electron` in a
+   concrete and reviewable manner.
+
+## Asking for General Help
+
+Because the level of activity in the `electron/electron` repository is
+so high, questions or requests for general help using Electron should
+be directed at the [community slack channel](https://atomio.slack.com)
+or the [forum](https://discuss.atom.io/c/electron).
+
+## Submitting a Bug Report
+
+When opening a new issue in the `electron/electron` issue tracker, users
+will be presented with a template that should be filled in.
+
+```markdown
+<!--
+Thanks for opening an issue! A few things to keep in mind:
+
+- The issue tracker is only for bugs and feature requests.
+- Before reporting a bug, please try reproducing your issue against
+  the latest version of Electron.
+- If you need general advice, join our Slack: http://atom-slack.herokuapp.com
+-->
+
+* Electron version:
+* Operating system:
+
+### Expected behavior
+
+<!-- What do you think should happen? -->
+
+### Actual behavior
+
+<!-- What actually happens? -->
+
+### How to reproduce
+
+<!--
+
+Your best chance of getting this bug looked at quickly is to provide a REPOSITORY that can be cloned and run.
+
+You can fork https://github.com/electron/electron-quick-start and include a link to the branch with your changes.
+
+If you provide a URL, please list the commands required to clone/setup/run your repo e.g.
+
+  $ git clone $YOUR_URL -b $BRANCH
+  $ npm install
+  $ npm start || electron .
+
+-->
+```
+
+If you believe that you have found a bug in Electron, please fill out this
+form to the best of your ability.
+
+The two most important pieces of information needed to evaluate the report are
+a description of the bug and a simple test case to recreate it. It easier to fix
+a bug if it can be reproduced.
+
+See [How to create a Minimal, Complete, and Verifiable example](https://stackoverflow.com/help/mcve).
+
+## Triaging a Bug Report
+
+It's common for open issues to involve discussion. Some contributors may
+have differing opinions, including whether the behavior is a bug or feature.
+This discussion is part of the process and should be kept focused, helpful,
+and professional.
+
+Terse responses that provide neither additional context nor supporting detail
+are not helpful or professional. To many, such responses are annoying and
+unfriendly.
+
+Contributors are encouraged to solve issues collaboratively and help one
+another make progress. If encounter an issue that you feel is invalid, or
+which contains incorrect information, explain *why* you feel that way with
+additional supporting context, and be willing to be convinced that you may
+be wrong. By doing so, we can often reach the correct outcome faster.
+
+## Resolving a Bug Report
+
+Most issues are resolved by opening a pull request. The process for opening and
+reviewing a pull request is similar to that of opening and triaging issues, but
+carries with it a necessary review and approval workflow that ensures that the
+proposed changes meet the minimal quality and functional guidelines of the
+Electron project.