Contributing to the Atom GitHub Package
For general contributing information, see the Atom contributing guide; however, right now, contributing to the GitHub package differs from contributing to other core Atom packages in some ways.
In particular, the GitHub package is under constant development by a portion of the core Atom team, and there is currently a clear vision for short- to medium-term features and enhancements. That doesn't mean we won't merge pull requests or fix other issues, but it does mean that you should consider discussing things with us first so that you don't spend time implementing things in a way that differs from the patterns we want to establish or build a feature that we're already working on.
Technical contribution tips
Updating the GraphQL Schema
This project uses Relay for its GitHub integration. There's a source-level transform that depends on having a local copy of the GraphQL schema available. If you need to update the local schema to the latest version, run
GITHUB_TOKEN=abcdef0123456789 npm run fetch-schema
abcdef0123456789 is a token generated as per the Creating a personal access token for the command line help article.
Please check in the generated
In addition, if you make any changes to any of the GraphQL queries or fragments (inside the
graphql tagged template literals), you will need to run
npm run relay to regenerate the statically-generated query files.
To run tests, open the command palette and select "Run Package Specs". This will open a new window running "GitHub Package Tests". If the window stays blank for more than a few seconds, open DevTools and check for error messages.
To re-run tests, you can refresh that window by pressing
Cmd + R in DevTools.
You can also run them on the command line with
npm run test.
Sometimes it's necessary to test async operations. For example, imagine the following test:
// Fails let value = 0; setTimeout(() => value = 1) assert.equal(value, 1)
You could write this test using a promise along with the
// Passes, but not ideal import until from 'test-until' let value = 0; setTimeout(() => value = 1) await until(() => value === 1)
However, we lose the information about the failure ('expected 0 to equal 1') and the test is harder to read (you have to parse the
until expression to figure out what the assertion really is).
The GitHub package includes a Babel transform that makes this a little nicer; just add
.async to your
assert (and don't forget to
// Passes! let value = 0; setTimeout(() => value = 1) await assert.async.equal(value, 1)
This transpiles into a form similar to the one above, so is asynchronous, but if the test fails, we'll still see a message that contains 'expected 0 to equal 1'.
When writing tests that depend on values that get set asynchronously, prefer
assert.async.x(...) over other forms.
Living on the edge
If you're working on the GitHub package day-to-day, it's useful to have a development environment configured to use the latest and greatest source.
Build Atom from master frequently if you can. This will help us notice any changes in Atom core that cause regressions.
Install the GitHub package from its git URL:
$ apm install atom/github
When you run Atom in non-dev-mode (
atom .) you'll be running the latest merged code in this repository. If this isn't stable enough for day-to-day work, then we have bugs to fix
Link your GitHub package source in dev mode:
# In the root directory of your atom/github clone $ apm link --dev .
When you run Atom in dev mode (
atom -d .) you'll be running your local changes. This is useful for reproducing bugs or trying out new changes live before merging them.