Skip to content

Latest commit

 

History

History
123 lines (106 loc) · 5.47 KB

CONTRIBUTING.md

File metadata and controls

123 lines (106 loc) · 5.47 KB
Raw

Contributing to Atom

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to Atom and its packages, which are hosted in the Atom Organization on GitHub. If you're unsure which package is causing your problem or if you're having an issue with Atom core, please open an issue on the main atom repository. These are just guidelines, not rules, use your best judgement and feel free to propose changes to this document in a pull request.

Submitting Issues

  • Include the version of Atom you are using and the OS.
  • 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 to include. If the dev tools 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.
  • On Mac, 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.

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 Atom organization such as tabs, find-and-replace, language-javascript, and atom-light-ui.

For more information on how to work with Atom's official packages, see Contributing to Atom Packages

Pull Requests

  • Include screenshots and animated GIFs in your pull request whenever possible.
  • Follow the CoffeeScript, JavaScript, and CSS styleguides.
  • Include thoughtfully-worded, well-structured Jasmine specs.
  • Document new code based on the Documentation Styleguide
  • 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.

Git Commit Messages

  • 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:
    • 💄 :lipstick: when improving the format/structure of the code
    • 🐎 :racehorse: when improving performance
    • 🚱 :non-potable_water: when plugging memory leaks
    • 📝 :memo: when writing docs
    • 🐧 :penguin: when fixing something on Linux
    • 🍎 :apple: when fixing something on Mac OS
    • 🏁 :checkered_flag: when fixing something on Windows
    • 🐛 :bug: when fixing a bug
    • 🔥 :fire: when removing code or files
    • 💚 :green_heart: when fixing the CI build
    • ✅ :white_check_mark: when adding tests
    • 🔒 :lock: when dealing with security

CoffeeScript Styleguide

  • Set parameter defaults without spaces around the equal sign
    • 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.

Documentation Styleguide

  • Use TomDoc.
  • Use Markdown.
  • 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}
    • Delegate to comments elsewhere with {Delegates to: ClassName.methodName} style notation.

Example

# 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) ->