github/atom
1
1
Fork 0
mirror of https://github.com/atom/atom.git synced 2026-01-22 21:38:10 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1174 from atom/cj-update-docs

Browse Source 
Update docs
This commit is contained in:
Kevin Sawicki
2013-12-04 09:17:16 -08:00
parent 9b0f8ccee0 e2ee99556d
commit 2434db4dc2
3 changed files with 34 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
CONTRIBUTING.md
View File

@@ -1,67 +1,43 @@
# :rotating_light: Contributing to Atom :rotating_light:
# :tada: Contributing to Atom :tada:
These are just guidelines, not rules, use your best judgement and feel free
to propose changes to this document in a pull request.
## Issues
* Include screenshots and animated GIFs whenever possible, they are immensely
helpful
helpful.
* Include the behavior you expected to happen and other places you've seen
that behavior such as Emacs, vi, Xcode, etc.
* Check the Console app for stack traces to include if reporting a crash
* Check the Dev tools (`alt-cmd-i`) for errors and stack traces to include
* Check the Console app for stack traces to include if reporting a crash.
* Check the Dev tools (`alt-cmd-i`) for errors and stack traces to include.
## Code
## Pull Requests
* Include screenshots and animated GIFs whenever possible.
* Follow the [JavaScript](https://github.com/styleguide/javascript) and
[CSS](https://github.com/styleguide/css) styleguides
* Include thoughtfully worded [Jasmine](http://pivotal.github.com/jasmine/)
specs
* Add 3rd-party packages as a `package.json` dependency
* Commit messages are in the present tense
* Commit messages that improve the format of the code start with :lipstick:
* Commit messages that improve the performance start with :racehorse:
* Commit messages that remove memory leaks start with :non-potable_water:
* Commit messages that improve documentation start with :memo:
* Files end with a newline
* Avoid placing files in `vendor`. 3rd-party packages should be added as a
`package.json` dependency.
* Files end with a newline.
* Requires should be 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)
* Class variables and methods should be in the following order:
* Class variables (variables starting with a `@`)
* Class methods (methods starting with a `@`)
* Instance variables
* Instance methods
* Beware of platform differences
* The home directory is `process.env.USERPROFILE` on Windows, while on OS X
and Linux it's `process.env.HOME`
* Path separator is `\` on Windows, and is `/` on OS X and Linux, so use
`path.join` to concatenate filenames
* Use `require('atom').fs.getHomeDirectory()` to get the home directory.
* Use `path.join()` to concatenate filenames.
* Temporary directory is not `/tmp` on Windows, use `os.tmpdir()` when
possible
## Philosophy
### Write Beautiful Code
Once you get something working, take the time to consider whether you can achieve it in a more elegant way. We're planning on open-sourcing Atom, so let's put our best foot forward.
### When in doubt, pair-up
Pairing can be an effective and fun way to pass on culture, knowledge, and taste. If you can find the time, we encourage you to work synchronously with other community members of all experience levels to help the knowledge-mulching process. It doesn't have to be all the time; a little pairing goes a long way.
### Write tests, and write them first
The test suite keeps protects our codebase from the ravages of entropy, but it only works when we have thorough coverage. Before you write implementation code, write a failing test proving that it's needed.
### Leave the test suite better than you found it
Consider how the specs you are adding fit into the spec-file as a whole. Is this the right place for your spec? Does the spec need to be reorganized now that you're adding this extra dimension? Specs are only as useful as the next person's ability to understand them.
### Solve today's problem
Avoid adding flexibility that isn't needed *today*. Nothing is ever set in stone, and we can always go back and add flexibility later. Adding it early just means we have to pay for complexity that we might not end up using.
### Favor clarity over brevity or cleverness.
Three lines that someone else can read are better than one line that's tricky.
### Don't be defensive
Only catch exceptions that are truly exceptional. Assume that components we control will honor their contracts. If they don't, the solution is to find and fix the problem in code rather than cluttering the code with attempts to foresee all potential issues at runtime.
### Don't be afraid to add classes and methods
Code rarely suffers from too many methods and classes, and often suffers from too few. Err on the side of numerous short, well-named methods. Pull out classes with well-defined roles.
### Rip shit out
Don't be afraid to delete code. Don't be afraid to rewrite something that needs to be refreshed. If it's in version control, we can always resurrect it.
### Maintain a consistent level of abstraction
Every line in a method should read at the same basic level of abstraction. If there's a section of a method that goes into a lot more detail than the rest of the method, consider extracting a new method and giving it a clear name.
## Git Commit Messages
* Use the present tense
* 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

25
README.md
View File

@@ -1,30 +1,17 @@
# Atom — Futuristic Text Editing
# Atom — The hackable, ~~collaborative~~ editor of tomorrow!
![atom](https://s3.amazonaws.com/speakeasy/apps/icons/27/medium/7db16e44-ba57-11e2-8c6f-981faf658e00.png)
![Atom](https://www.atom.io/assets/logo-f725ebd356beb17f950b172f03d37244.png)
Check out our [guides](https://www.atom.io/docs/latest/) and [API documentation](https://www.atom.io/docs/api/v34.0.0/api/)
Check out our [guides and API documentation](https://www.atom.io/docs/latest/).
## Installing
Download the latest Atom release from [speakeasy](https://speakeasy.githubapp.com/apps/27).
Download the latest [Atom release](https://github.com/atom/atom/releases/latest).
It will automatically update when a new release is available.
Atom will automatically update when a new release is available.
## Building
### Requirements
* Mountain Lion
* Looking for Windows support? Read [here][building].
* Boxen (Obviously Atom won't release with this requirement)
### Installation
1. `gh-setup atom`
2. `cd ~/github/atom`
3. `script/build`
Follow the instructions in the [build docs][building].
[building]: https://github.com/atom/atom/blob/master/docs/building-atom.md

6
docs/building-atom.md
View File

@@ -6,10 +6,10 @@ atom][download].
## OSX
* Use Mountain Lion
* Use OS X 10.8 or later
* Install the latest node 0.10.x release (32bit preferable)
* Clone [atom][atom-git] to `~/github/atom`
* Run `~/github/atom/script/bootstrap`
* Run `~/github/atom/script/build`
## Windows
@@ -26,7 +26,7 @@ atom][download].
* Use the Windows GitHub shell and cd into `C:\Users\<user>\github\atom`
* Run `script\bootstrap`
[download]: http://www.atom.io
[download]: https://github.com/atom/atom/releases/latest
[win-node]: http://nodejs.org/download/
[win-python]: http://www.python.org/download/
[win-github]: http://windows.github.com/