From 459c11b602611021d6ba0f29cee3a64871297655 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 19 Feb 2014 08:40:02 -0700 Subject: [PATCH 1/7] Add initial doc for contributing to packages --- docs/contributing.md | 137 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 000000000..d26a49f99 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,137 @@ +# Contributing to Atom Packages + +The following is a set of guidelines for contributing to Atom packages, which +are hosted in the [Atom Organization](https://github.com/atom) on GitHub. If +you're unsure which package is causing your problem or if you're having an issue +with Atom core, please use the feedback form in the application or email +[atom@github.com](mailto:atom@github.com). + +## Submitting Issues + +* 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. +* Check the dev tools (`alt-cmd-i`) for errors and stack traces to include. +* Check Console.app for stack traces to include if reporting a crash. +* Perform a cursory search to see if a similar issue has already been submitted. + +## Hacking on Packages + +### Cloning + +The first step is creating your own clone. You can of course do this manually +with git, or you can use the `apm develop` command to create a clone based on +the package's `repository` field in the `package.json`. + +For example, if you want to make changes to the `tree-view` package, run the +following command: + +``` +> apm develop tree-view +Cloning https://github.com/atom/tree-view ✓ +Installing modules ✓ +~/.atom/dev/packages/tree-view -> ~/github/tree-view +``` + +### Running in Development Mode + +Editing a package in Atom is a bit of a circular experience: you're using Atom +to modify itself. What happens if you temporarily break something? You don't +want the version of Atom you're using to edit to become useless in the process. +For this reason, you'll only want to load packages in **development mode** while +you are working on them. You'll perform your editing in **stable mode**, only +switching to development mode to test your changes. + +To open a development mode window, use the "Application: Open Dev" command, +which is normally bound to `cmd-shift-o`. You can also run dev mode from the +command line with `atom -d`. + +To load your package in development mode, create a symlink to it in +`~/.atom/dev/packages`. This occurs automatically when you clone the package +with `apm develop`. You can also run `apm link -d` and `apm unlink -d` from the +package directory to create and remove dev-mode symlinks. + +### Installing Dependencies + +Finally, you need to install the cloned package's dependencies by running +`apm install` within the package directory. This step is also performed +automatically the first time you run `apm develop`, but you'll want to keep +dependencies up to date by running `apm update` after pulling upstream changes. + +## Submitting Pull Requests + +### Code Guidelines + +* 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 + [Jasmine](http://pivotal.github.com/jasmine) specs. +* Document new code based on the + [Documentation Styleguide](#documentation-styleguide) +* Avoid placing files in `vendor`. 3rd-party packages should be added as + dependencies in `package.json`. +* End files with a newline. +* Place requires in the following order: + * Built in Node Modules (such as `path`) + * Built in Atom and Atom Shell Modules (such as `atom`, `shell`) + * 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 `require('atom').fs.getHomeDirectory()` to get the home directory. + * Use `path.join()` to concatenate filenames. + * Use `os.tmpdir()` rather than `/tmp` when you need to reference the + temporary directory. + +### Commit Message Guidelines + * Use the present tense ("Add feature" not "Added feature") + * Use the imperative mood ("Fix bug" not "Fixes bug") + * Limit the first line to 72 characters or less + * Reference issues and pull requests liberally + * Consider starting the commit message with an applicable emoji: + * :lipstick: when improving the format/structure of the code + * :racehorse: when improving performance + * :non-potable_water: when plugging memory leaks + * :memo: when writing docs + +## CoffeeScript Styleguide + +* 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 }` +* Set parameter defaults without spaces around the equal sign: + * `clear = (count=1) ->` instead of `clear = (count = 1) ->` +* Include a single line of whitespace between methods. + +## Documentation Styleguide + +* Use [TomDoc](http://tomdoc.org). +* Use [Markdown](https://daringfireball.net/projects/markdown). +* Reference classes with the custom `{ClassName}` notation. +* Reference methods with the custom `{ClassName::methodName}` notation. + +### Example + +```coffee +# Public: Disable the package with the given name. +# +# This method emits multiple events: +# +# * `package-will-be-disabled` - before the package is disabled. +# * `package-disabled` - after the package is disabled. +# +# name - The {String} name of the package to disable. +# options - The {Object} with disable options (default: {}): +# :trackTime - `true` to track the amount of time disabling took. +# :ignoreErrors - `true` to catch and ignore errors thrown. +# callback - The {Function} to call after the package has been disabled. +# +# Returns `undefined`. +disablePackage: (name, options, callback) -> +``` From 2275a6d2d1578f55ff8d55068c93080f657fd0e7 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 19 Feb 2014 13:54:18 -0700 Subject: [PATCH 2/7] Use --dev instead of -d for clarity --- docs/contributing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index d26a49f99..0488dd4d9 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -45,12 +45,12 @@ switching to development mode to test your changes. To open a development mode window, use the "Application: Open Dev" command, which is normally bound to `cmd-shift-o`. You can also run dev mode from the -command line with `atom -d`. +command line with `atom --dev`. To load your package in development mode, create a symlink to it in `~/.atom/dev/packages`. This occurs automatically when you clone the package -with `apm develop`. You can also run `apm link -d` and `apm unlink -d` from the -package directory to create and remove dev-mode symlinks. +with `apm develop`. You can also run `apm link --dev` and `apm unlink --dev` +from the package directory to create and remove dev-mode symlinks. ### Installing Dependencies From 01f6ca3cae9174477ad15a960a40597b70e8997e Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 19 Feb 2014 13:57:19 -0700 Subject: [PATCH 3/7] Discuss clone location and ATOM_REPOS_HOME environment variable --- docs/contributing.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/contributing.md b/docs/contributing.md index 0488dd4d9..141ccdf3b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -34,6 +34,9 @@ Installing modules ✓ ~/.atom/dev/packages/tree-view -> ~/github/tree-view ``` +This clones the `tree-view` repository to `~/github`. If you prefer a different +path, specify it via the `ATOM_REPOS_HOME` environment variable. + ### Running in Development Mode Editing a package in Atom is a bit of a circular experience: you're using Atom From aebca38ae6984993b712f122703fba5c14632471 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 19 Feb 2014 14:01:03 -0700 Subject: [PATCH 4/7] Use a better imperative mood example --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 141ccdf3b..43b58aeba 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -92,7 +92,7 @@ dependencies up to date by running `apm update` after pulling upstream changes. ### Commit Message Guidelines * Use the present tense ("Add feature" not "Added feature") - * Use the imperative mood ("Fix bug" not "Fixes bug") + * 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: From 029e4336bc90107b5ee19c115b1d7c18a3272337 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 19 Feb 2014 15:09:06 -0700 Subject: [PATCH 5/7] Add a link to the Emoji Cheat Sheet --- docs/contributing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contributing.md b/docs/contributing.md index 43b58aeba..8a02ec4f4 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -100,6 +100,8 @@ dependencies up to date by running `apm update` after pulling upstream changes. * :racehorse: when improving performance * :non-potable_water: when plugging memory leaks * :memo: when writing docs + * :bulb: Check out the [Emoji Cheat Sheet](http://www.emoji-cheat-sheet.com) + for more ideas. ## CoffeeScript Styleguide From 280fc9af856103a810bbb94b6ed8a867f7981b09 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 19 Feb 2014 15:12:28 -0700 Subject: [PATCH 6/7] Go back to old biscotto syntax until it's updated --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 8a02ec4f4..7e2cf9777 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -119,7 +119,7 @@ dependencies up to date by running `apm update` after pulling upstream changes. * Use [TomDoc](http://tomdoc.org). * Use [Markdown](https://daringfireball.net/projects/markdown). * Reference classes with the custom `{ClassName}` notation. -* Reference methods with the custom `{ClassName::methodName}` notation. +* Reference methods with the custom `{ClassName.methodName}` notation. ### Example From 383d8f694025d7dcc747b50c45ac5df554bb02a3 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 19 Feb 2014 15:12:49 -0700 Subject: [PATCH 7/7] Don't mention vendor --- docs/contributing.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 7e2cf9777..b042275c5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -74,8 +74,6 @@ dependencies up to date by running `apm update` after pulling upstream changes. [Jasmine](http://pivotal.github.com/jasmine) specs. * Document new code based on the [Documentation Styleguide](#documentation-styleguide) -* Avoid placing files in `vendor`. 3rd-party packages should be added as - dependencies in `package.json`. * End files with a newline. * Place requires in the following order: * Built in Node Modules (such as `path`)