2017-04-21 05:08:23 +00:00
# Contributing to GitHub Desktop
2018-02-01 23:08:53 +00:00
:+1: :tada: :sparkling_heart: Thanks for your interest! :sparkling_heart: :tada: :+1:
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
The following is a set of guidelines for contributing to GitHub Desktop and its
2018-02-01 23:08:53 +00:00
related projects, which are hosted in the [Desktop organization ](https://github.com/desktop )
on GitHub. These are just guidelines, not rules. Use your best judgment, and
feel free to propose changes to this document in a pull request.
2017-04-21 05:08:23 +00:00
2017-11-28 04:54:42 +00:00
Note that GitHub Desktop is an evolving project, so expect things to change over
time as the team learns, listens and refines how we work with the community.
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
#### Table Of Contents
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
[What should I know before I get started? ](#what-should-i-know-before-i-get-started )
2018-02-01 23:08:53 +00:00
* [Code of Conduct ](#code-of-conduct )
* [The Roadmap ](#the-roadmap )
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
[How Can I Contribute? ](#how-can-i-contribute )
2018-02-01 23:08:53 +00:00
* [Reporting Bugs ](#reporting-bugs )
* [Suggesting Enhancements ](#suggesting-enhancements )
* [Help Wanted ](#help-wanted )
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
[Additional Notes ](#additional-notes )
2018-02-01 23:08:53 +00:00
* [Issue and Pull Request Labels ](#issue-and-pull-request-labels )
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
## What should I know before I get started?
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
### Code of Conduct
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
This project adheres to the Contributor Covenant [code of conduct ](CODE_OF_CONDUCT.md ).
By participating, you are expected to uphold this code.
Please report unacceptable behavior to [opensource+desktop@github.com ](mailto:opensource+desktop@github.com ).
2017-04-21 05:08:23 +00:00
2017-11-28 04:54:42 +00:00
### The Roadmap
2017-04-21 05:08:23 +00:00
2017-11-28 21:10:58 +00:00
GitHub Desktop recently announced its
2017-11-28 04:54:42 +00:00
[1.0 release ](https://github.com/blog/2437-announcing-github-desktop-1-0 ) and
are working towards deprecating the classic Mac and Windows applications.
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
Beyond that, we are working on a roadmap you can read [here ](https://github.com/desktop/desktop/blob/master/docs/process/roadmap.md ).
2017-11-28 04:54:42 +00:00
The immediate milestones are more detailed, and the latter milestones are more
fuzzy and subject to change.
If you have ideas or suggestions please read the
[Suggesting Enhancements ](#suggesting-enhancements ) section below to understand
how to contribute your feedback.
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
## How Can I Contribute?
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
### Reporting Bugs
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
This section guides you through submitting a bug report for GitHub Desktop.
Following these guidelines helps maintainers and the community understand your
report :pencil:, reproduce the behavior :computer: :computer:, and find related
reports :mag_right:.
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
Before creating bug reports, please check [this list ](#before-submitting-a-bug-report )
as you might find out that you don't need to create one. When you are creating
a bug report, please [include as many details as possible ](#how-do-i-submit-a-good-bug-report ).
Fill out [the required template ](./.github/ISSUE_TEMPLATE.md ), the information
it asks for helps us resolve issues faster.
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
#### Before Submitting A Bug Report
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
**Perform a [cursory search ](https://github.com/desktop/desktop/labels/bug )**
to see if the problem has already been reported. If it does exist, add a
:thumbsup: to the issue to indicate this is also an issue for you, and add a
comment to the existing issue if there is extra information you can contribute.
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
#### How Do I Submit A (Good) Bug Report?
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
Bugs are tracked as [GitHub issues ](https://guides.github.com/features/issues/ ).
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
Simply create an issue on the [GitHub Desktop issue tracker ](https://github.com/desktop/desktop/issues )
and fill out the provided [issue template ](./.github/ISSUE_TEMPLATE.md ).
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
The information we are interested in includes:
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
- details about your environment - which build, which operating system
- details about reproducing the issue - what steps to take, what happens, how
often it happens
- other relevant information - log files, screenshots, etc.
2017-04-21 07:08:06 +00:00
2017-05-04 02:57:57 +00:00
### Suggesting Enhancements
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
This section guides you through submitting an enhancement suggestion for
GitHub Desktop, including completely new features and minor improvements to
existing functionality. Following these guidelines helps maintainers and the
community understand your suggestion :pencil: and find related suggestions
:mag_right:.
2017-04-21 05:08:23 +00:00
2018-02-01 23:08:53 +00:00
Before creating enhancement suggestions, please check [this list ](#before-submitting-an-enhancement-suggestion )
as you might find out that you don't need to create one. When you are creating
an enhancement suggestion, please [include as many details as possible ](#how-do-i-submit-a-good-enhancement-suggestion ).
Fill in [the template ](./.github/ISSUE_TEMPLATE.md ), including the steps
that you imagine you would take if the feature you're requesting existed.
2017-04-21 05:08:23 +00:00
2017-05-04 02:57:57 +00:00
#### Before Submitting An Enhancement Suggestion
2018-02-01 23:08:53 +00:00
**Perform a [cursory search ](https://github.com/desktop/desktop/labels/enhancement )**
to see if the enhancement has already been suggested. If it has, add a
:thumbsup: to indicate your interest in it, or comment if there is additional
information you would like to add.
2017-05-04 02:57:57 +00:00
#### How Do I Submit A (Good) Enhancement Suggestion?
2018-02-01 23:08:53 +00:00
Enhancement suggestions are tracked as [GitHub issues ](https://guides.github.com/features/issues/ ).
2017-05-04 02:57:57 +00:00
2018-02-01 23:08:53 +00:00
Simply create an issue on the [GitHub Desktop issue tracker ](https://github.com/desktop/desktop/issues )
and provide the following information:
2017-05-04 02:57:57 +00:00
* **Use a clear and descriptive title** for the issue to identify the
suggestion.
2018-02-01 23:08:53 +00:00
* **Provide a step-by-step description of the suggested enhancement** in as
much detail as possible. This additional context helps the maintainers to
2017-05-04 02:57:57 +00:00
understand the enhancement from your perspective
* **Explain why this enhancement would be useful** to GitHub Desktop users.
2017-06-26 14:33:41 +00:00
* **Include screenshots and animated GIFs** if relevant to help you demonstrate
2017-05-04 02:57:57 +00:00
the steps or point out the part of GitHub Desktop which the suggestion is
related to. You can use [this tool ](http://www.cockos.com/licecap/ ) to record
GIFs on macOS and Windows.
* **List some other applications where this enhancement exists, if applicable.**
2017-09-14 02:54:15 +00:00
### Help Wanted
2017-05-04 02:57:57 +00:00
2017-06-29 19:12:41 +00:00
As part of building GitHub Desktop, we'll identify tasks that are good for
external contributors to pick up. These tasks:
2017-05-04 02:57:57 +00:00
2018-02-01 23:08:53 +00:00
- have low impact, or have a known workaround
- should be addressed
- have a narrow scope and/or easy reproduction steps
- can be worked on independent of other tasks
2017-05-04 02:57:57 +00:00
2018-02-01 23:08:53 +00:00
These issues will be labelled as [`help wanted` ](https://github.com/desktop/desktop/labels/help%20wanted )
in the repository. If you are interested in contributing to the project, please
comment on the issue to let the core team (and the community) know you are
interested in the issue.
2017-05-04 02:57:57 +00:00
## Additional Notes
### Issue and Pull Request Labels
2018-02-01 23:08:53 +00:00
This section lists the labels we use to help us track and manage issues and
pull requests.
2017-05-04 02:57:57 +00:00
#### Type of Issue and Issue State
2018-02-01 23:08:53 +00:00
| Label name | :mag_right: | Description |
| --- | --- | --- |
| `enhancement` | [search ](https://github.com/desktop/desktop/labels/enhancement ) | Feature requests. |
| `bug` | [search ](https://github.com/desktop/desktop/labels/bug ) | Confirmed bugs or reports that are very likely to be bugs. |
2017-05-04 02:57:57 +00:00
| `more-information-needed` | [search ](https://github.com/desktop/desktop/labels/more-information-needed ) | More information needs to be collected about these problems or feature requests (e.g. steps to reproduce). |
2018-02-22 05:40:26 +00:00
| `reviewer-needs-to-reproduce` | [search ](https://github.com/desktop/desktop/labels/reviewer-needs-to-reproduce ) | Likely bugs, but haven't been reliably reproduced by a reviewer. |
2018-02-01 23:08:53 +00:00
| `stale` | [search ](https://github.com/desktop/desktop/labels/stale ) | Issues that are inactive and marked to be closed. |
| `macOS` | [search ](https://github.com/desktop/desktop/labels/macOS ) | Issues specific to macOS users. |
| `Windows` | [search ](https://github.com/desktop/desktop/labels/Windows ) | Issues specific to Windows users. |
| `codemirror` | [search ](https://github.com/desktop/desktop/labels/codemirror ) | Issues related to our use of [CodeMirror ](https://codemirror.net/ ) that may require upstream fixes. |
| `electron` | [search ](https://github.com/desktop/desktop/labels/electron ) | Issues related to our use of [Electron ](https://electron.atom.io ) that may require upstream fixes. |
2017-05-04 02:57:57 +00:00
#### Topics
2018-02-01 23:08:53 +00:00
| Label name | :mag_right: | Description |
| --- | --- | --- |
| `help wanted` | [search ](https://github.com/desktop/desktop/labels/help%20wanted ) | Issues marked as ideal for external contributors. |
| `tech-debt` | [search ](https://github.com/desktop/desktop/labels/tech-debt ) | Issues related to code or architecture decisions. |
| `needs-design-input` | [search ](https://github.com/desktop/desktop/labels/needs-design-input ) | Issues that require design input from the core team before the work can be started. |
2017-05-04 02:57:57 +00:00
#### Workflow
2018-02-01 23:08:53 +00:00
| Label name | :mag_right: | Description |
| --- | --- | --- |
2018-03-23 02:05:38 +00:00
| `infrastructure` | [search ](https://github.com/desktop/desktop/labels/infrastructure ) | Pull requests not related to the core application - documentation, dependencies, tooling, etc. |
2018-02-01 23:08:53 +00:00
| `ready-for-review` | [search ](https://github.com/desktop/desktop/labels/ready-for-review ) | Pull Requests that are ready to be reviewed by the maintainers. |
