2014-05-27 21:41:24 +04:00
|
|
|
# Contributing to Atom
|
|
|
|
|
|
|
|
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
|
2013-08-12 10:18:58 +04:00
|
|
|
|
2014-05-19 06:45:03 +04:00
|
|
|
The following is a set of guidelines for contributing to Atom and its packages,
|
|
|
|
which are hosted in the [Atom Organization](https://github.com/atom) on GitHub.
|
2015-03-27 04:48:07 +03:00
|
|
|
These are just guidelines, not rules, use your best judgment and feel free to
|
2014-05-27 21:43:08 +04:00
|
|
|
propose changes to this document in a pull request.
|
2013-12-04 20:55:19 +04:00
|
|
|
|
2014-05-19 06:45:03 +04:00
|
|
|
## Submitting Issues
|
|
|
|
|
2015-04-07 14:38:57 +03:00
|
|
|
* You can create an issue [here](https://github.com/atom/atom/issues/new), but
|
|
|
|
before doing that please read the notes below on debugging and submitting issues,
|
|
|
|
and include as many details as possible with your report.
|
2015-03-12 01:05:48 +03:00
|
|
|
* Check the [debugging guide](https://atom.io/docs/latest/hacking-atom-debugging) for tips
|
2014-10-15 04:27:53 +04:00
|
|
|
on debugging. You might be able to find the cause of the problem and fix
|
2014-06-15 15:10:04 +04:00
|
|
|
things yourself.
|
2014-06-04 19:31:11 +04:00
|
|
|
* Include the version of Atom you are using and the OS.
|
2014-05-19 06:45:03 +04:00
|
|
|
* Include screenshots and animated GIFs whenever possible; they are immensely
|
|
|
|
helpful.
|
|
|
|
* Include the behavior you expected and other places you've seen that behavior
|
|
|
|
such as Emacs, vi, Xcode, etc.
|
2014-10-15 04:27:53 +04:00
|
|
|
* Check the dev tools (`alt-cmd-i`) for errors to include. If the dev tools
|
2014-06-04 19:22:55 +04:00
|
|
|
are open _before_ the error is triggered, a full stack trace for the error
|
|
|
|
will be logged. If you can reproduce the error, use this approach to get the
|
|
|
|
full stack trace and include it in the issue.
|
2014-05-19 06:45:03 +04:00
|
|
|
* On Mac, check Console.app for stack traces to include if reporting a crash.
|
2015-04-07 14:38:57 +03:00
|
|
|
* Perform a [cursory search](https://github.com/issues?q=+is%3Aissue+user%3Aatom)
|
|
|
|
to see if a similar issue has already been submitted.
|
2014-10-27 20:42:29 +03:00
|
|
|
* Please setup a [profile picture](https://help.github.com/articles/how-do-i-set-up-my-profile-picture)
|
|
|
|
to make yourself recognizable and so we can all get to know each other better.
|
2014-03-10 22:13:08 +04:00
|
|
|
|
2013-12-05 20:50:13 +04:00
|
|
|
### Package Repositories
|
|
|
|
|
|
|
|
This is the repository for the core Atom editor only. Atom comes bundled with
|
|
|
|
many packages and themes that are stored in other repos under the
|
2014-05-19 06:45:03 +04:00
|
|
|
[Atom organization](https://github.com/atom) such as
|
|
|
|
[tabs](https://github.com/atom/tabs),
|
2013-12-05 20:50:13 +04:00
|
|
|
[find-and-replace](https://github.com/atom/find-and-replace),
|
2014-05-19 06:45:03 +04:00
|
|
|
[language-javascript](https://github.com/atom/language-javascript), and
|
2015-01-31 12:59:45 +03:00
|
|
|
[atom-light-ui](https://github.com/atom/atom-light-ui).
|
2013-12-05 20:50:13 +04:00
|
|
|
|
2015-04-07 14:38:57 +03:00
|
|
|
If your issue is related to a specific package, open an issue on that package's
|
|
|
|
issue tracker. If you're unsure which package is causing your problem or if
|
|
|
|
you're having an issue with Atom core, open an issue on this repository.
|
|
|
|
|
2014-05-21 22:35:23 +04:00
|
|
|
For more information on how to work with Atom's official packages, see
|
2015-03-12 21:24:14 +03:00
|
|
|
[Contributing to Atom Packages](https://github.com/atom/atom/blob/master/docs/contributing-to-packages.md)
|
2014-05-19 06:45:03 +04:00
|
|
|
|
2013-11-27 23:20:22 +04:00
|
|
|
## Pull Requests
|
2014-05-19 06:45:03 +04:00
|
|
|
|
|
|
|
* Include screenshots and animated GIFs in your pull request whenever possible.
|
|
|
|
* Follow the [CoffeeScript](#coffeescript-styleguide),
|
|
|
|
[JavaScript](https://github.com/styleguide/javascript),
|
|
|
|
and [CSS](https://github.com/styleguide/css) styleguides.
|
|
|
|
* Include thoughtfully-worded, well-structured
|
2015-04-01 22:04:11 +03:00
|
|
|
[Jasmine](http://jasmine.github.io/) specs in the `./spec` folder. Run them using `apm test`. See the [Specs Styleguide](#specs-styleguide) below.
|
2014-05-19 06:45:03 +04:00
|
|
|
* Document new code based on the
|
|
|
|
[Documentation Styleguide](#documentation-styleguide)
|
|
|
|
* End files with a newline.
|
|
|
|
* Place requires in the following order:
|
2013-12-04 20:50:07 +04:00
|
|
|
* Built in Node Modules (such as `path`)
|
|
|
|
* Built in Atom and Atom Shell Modules (such as `atom`, `shell`)
|
|
|
|
* Local Modules (using relative paths)
|
2014-05-19 06:45:03 +04:00
|
|
|
* Place class properties in the following order:
|
|
|
|
* Class methods and properties (methods starting with a `@`)
|
|
|
|
* Instance methods and properties
|
|
|
|
* Avoid platform-dependent code:
|
2015-04-09 21:32:06 +03:00
|
|
|
* Use `require('fs-plus').getHomeDirectory()` to get the home directory.
|
2013-11-27 23:20:22 +04:00
|
|
|
* Use `path.join()` to concatenate filenames.
|
2014-05-19 06:45:03 +04:00
|
|
|
* Use `os.tmpdir()` rather than `/tmp` when you need to reference the
|
|
|
|
temporary directory.
|
2014-10-09 01:17:57 +04:00
|
|
|
* Using a plain `return` when returning explicitly at the end of a function.
|
|
|
|
* Not `return null`, `return undefined`, `null`, or `undefined`
|
2013-12-04 20:53:24 +04:00
|
|
|
|
|
|
|
## Git Commit Messages
|
2014-05-19 06:45:03 +04:00
|
|
|
|
|
|
|
* 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
|
|
|
|
* Consider starting the commit message with an applicable emoji:
|
2015-01-17 01:08:33 +03:00
|
|
|
* :art: `:art:` when improving the format/structure of the code
|
2014-05-06 19:22:01 +04:00
|
|
|
* :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
|
2014-05-15 21:10:40 +04:00
|
|
|
* :apple: `:apple:` when fixing something on Mac OS
|
2014-05-26 05:28:02 +04:00
|
|
|
* :checkered_flag: `:checkered_flag:` when fixing something on Windows
|
2014-05-19 06:45:03 +04:00
|
|
|
* :bug: `:bug:` when fixing a bug
|
2014-05-15 22:50:06 +04:00
|
|
|
* :fire: `:fire:` when removing code or files
|
2014-05-13 04:05:31 +04:00
|
|
|
* :green_heart: `:green_heart:` when fixing the CI build
|
|
|
|
* :white_check_mark: `:white_check_mark:` when adding tests
|
2014-05-17 02:01:21 +04:00
|
|
|
* :lock: `:lock:` when dealing with security
|
2014-10-15 04:28:19 +04:00
|
|
|
* :arrow_up: `:arrow_up:` when upgrading dependencies
|
2014-12-22 21:27:05 +03:00
|
|
|
* :arrow_down: `:arrow_down:` when downgrading dependencies
|
2015-01-15 20:57:38 +03:00
|
|
|
* :shirt: `:shirt:` when removing linter warnings
|
2013-12-12 02:34:51 +04:00
|
|
|
|
|
|
|
## CoffeeScript Styleguide
|
|
|
|
|
|
|
|
* Set parameter defaults without spaces around the equal sign
|
2014-05-19 06:45:03 +04:00
|
|
|
* `clear = (count=1) ->` instead of `clear = (count = 1) ->`
|
|
|
|
* Use parentheses if it improves code clarity.
|
|
|
|
* Prefer alphabetic keywords to symbolic keywords:
|
|
|
|
* `a is b` instead of `a == b`
|
|
|
|
* Avoid spaces inside the curly-braces of hash literals:
|
|
|
|
* `{a: 1, b: 2}` instead of `{ a: 1, b: 2 }`
|
|
|
|
* Include a single line of whitespace between methods.
|
2015-01-13 05:06:36 +03:00
|
|
|
* Capitalize initialisms and acronyms in names, except for the first word, which
|
|
|
|
should be lower-case:
|
|
|
|
* `getURI` instead of `getUri`
|
|
|
|
* `uriToOpen` instead of `URIToOpen`
|
2015-03-19 21:10:15 +03:00
|
|
|
* Use `slice()` to copy an array
|
|
|
|
* Add an explicit `return` when your function ends with a `for`/`while` loop and
|
|
|
|
you don't want it to return a collected array.
|
2014-02-07 02:20:08 +04:00
|
|
|
|
2015-04-01 22:04:11 +03:00
|
|
|
## Specs Styleguide
|
|
|
|
|
|
|
|
- Include thoughtfully-worded, well-structured
|
|
|
|
[Jasmine](http://jasmine.github.io/) specs in the `./spec` folder.
|
|
|
|
- treat `describe` as a noun or situation.
|
2015-04-01 22:10:02 +03:00
|
|
|
- treat `it` as a statement about state or how an operation changes state.
|
2015-04-01 22:04:11 +03:00
|
|
|
|
|
|
|
### Example
|
|
|
|
|
|
|
|
```coffee
|
2015-04-02 00:37:42 +03:00
|
|
|
describe 'a dog', ->
|
|
|
|
it 'barks', ->
|
2015-04-01 22:04:11 +03:00
|
|
|
# spec here
|
2015-04-02 00:37:42 +03:00
|
|
|
describe 'when the dog is happy', ->
|
|
|
|
it 'wags its tail', ->
|
2015-04-01 22:04:11 +03:00
|
|
|
# spec here
|
|
|
|
```
|
|
|
|
|
2014-02-07 02:20:08 +04:00
|
|
|
## Documentation Styleguide
|
|
|
|
|
2014-10-29 21:56:29 +03:00
|
|
|
* Use [AtomDoc](https://github.com/atom/atomdoc).
|
2014-02-07 02:38:14 +04:00
|
|
|
* Use [Markdown](https://daringfireball.net/projects/markdown).
|
2014-05-19 06:45:03 +04:00
|
|
|
* Reference methods and classes in markdown with the custom `{}` notation:
|
|
|
|
* Reference classes with `{ClassName}`
|
|
|
|
* Reference instance methods with `{ClassName::methodName}`
|
|
|
|
* Reference class methods with `{ClassName.methodName}`
|
2014-02-07 02:28:10 +04:00
|
|
|
|
|
|
|
### Example
|
|
|
|
|
|
|
|
```coffee
|
|
|
|
# Public: Disable the package with the given name.
|
|
|
|
#
|
2014-10-29 21:56:29 +03:00
|
|
|
# * `name` The {String} name of the package to disable.
|
|
|
|
# * `options` (optional) The {Object} with disable options (default: {}):
|
|
|
|
# * `trackTime` A {Boolean}, `true` to track the amount of time taken.
|
|
|
|
# * `ignoreErrors` A {Boolean}, `true` to catch and ignore errors thrown.
|
|
|
|
# * `callback` The {Function} to call after the package has been disabled.
|
2014-02-07 02:28:10 +04:00
|
|
|
#
|
|
|
|
# Returns `undefined`.
|
2014-02-07 03:55:13 +04:00
|
|
|
disablePackage: (name, options, callback) ->
|
2014-02-07 02:28:10 +04:00
|
|
|
```
|