You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Dec 15, 2022. It is now read-only.
For general contributing information, see the [Atom contributing guide](https://github.com/atom/atom/blob/master/CONTRIBUTING.md); however, right now, contributing to the GitHub package differs from contributing to other core Atom packages in some ways.
3
+
For general contributing information, see the [Atom contributing guide](https://github.com/atom/atom/blob/master/CONTRIBUTING.md); however, contributing to the GitHub package differs from contributing to other core Atom packages in some ways.
4
4
5
5
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.
6
6
7
-
Feel free to [open an issue](https://github.com/atom/github/issues) if you want to discuss anything with us. If you're curious what we're working on and will be working on in the near future, you can take a look at [our short-term roadmap](https://github.com/atom/github/projects/8).
7
+
Feel free to [open an issue](https://github.com/atom/github/issues) if you want to discuss anything with us. Depending on the scope and complexity of your proposal we may ask you to reframe it as a [Feature Request](/docs/how-we-work.md#new-features). If you're curious what we're working on and will be working on in the near future, you can take a look at [our most recent sprint project](https://github.com/atom/github/project) or [accepted Feature Requests](/docs/feature-requests/).
8
+
9
+
## Getting started
10
+
11
+
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.
12
+
13
+
1. Run an [Atom nightly build](https://github.com/atom/atom-nightly-releases) if you can. Occasionally, we depend on upstream changes in Atom that have not yet percolated through to stable builds. This will also help us notice any changes in Atom core that cause regressions. It may also be convenient to create shell aliases from `atom` to `atom-nightly` and `apm` to `apm-nightly`.
14
+
2. Install the GitHub package from its git URL:
15
+
16
+
```sh
17
+
apm-nightly install atom/github
18
+
```
19
+
20
+
When you run Atom in non-dev-mode (`atom-nightly .`) 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 :wink:
21
+
3. Link your GitHub package source in dev mode:
22
+
23
+
```sh
24
+
# In the root directory of your atom/github clone
25
+
apm-nightly link --dev .
26
+
```
27
+
28
+
When you run Atom in dev mode (`atom-nightly -d .`) you'll be running your local changes. This is useful for reproducing bugs or trying out new changes live before merging them.
29
+
30
+
### Running tests
31
+
32
+
The GitHub package's specs may be run with Atom's graphical test runner or from the command line.
33
+
34
+
Launch the graphical test runner by executing `Window: Run Package Specs` from the command palette. Once a test window is visible, tests may be re-run by refreshing it with cmd-R. Toggle the developer tools within the test runner window with cmd-shift-I to see syntax errors, warnings, or the output from `console.log` debug statements.
35
+
36
+
To run tests from the command line, use:
37
+
38
+
```sh
39
+
atom-nightly --test test/
40
+
```
41
+
42
+
If this process exits with no output and a nonzero exit status, try:
Occasionally, a test unrelated to your changes may fail sporadically. We file issues for these with the ["flaky-test" label](https://github.com/atom/github/issues?q=is%3Aissue+is%3Aopen+label%3Aflaky-test) and add a retry statement:
51
+
52
+
```js
53
+
it('passes sometimes and fails sometimes', function() {
54
+
this.retries(5); // FLAKE
55
+
56
+
// ..
57
+
})
58
+
```
59
+
60
+
If that isn't enough to pass the suite reliably -- for example, if a failure manipulates some global state to cause it to fail again on the retries -- skip the test until we can investigate further:
61
+
62
+
```js
63
+
// FLAKE
64
+
it.skip('breaks everything horribly when it fails', function() {
65
+
// ..
66
+
});
67
+
```
68
+
69
+
If you wish to help make these more reliable (for which we would be eternally grateful! :pray:) we have a helper that focuses and re-runs a single `it` or `describe` block many times:
70
+
71
+
```js
72
+
it.stress(100, 'seems to break sometimes', function() {
73
+
//
74
+
});
75
+
```
76
+
77
+
### Style and formatting
78
+
79
+
We enforce style consistency with eslint and the [fbjs-opensource](https://github.com/facebook/fbjs/tree/master/packages/eslint-config-fbjs-opensource) ruleset. Our CI will automatically verify that pull requests conform to the existing ruleset. If you wish to check your changes against our rules before you submit a pull request, run:
80
+
81
+
```sh
82
+
npm run lint
83
+
```
84
+
85
+
It's often more convenient to have Atom automatically lint and correct your source as you edit. To set this up, you'll need to install a frontend and a backend linter packages. I use [linter-eslint](https://atom.io/packages/linter-eslint) as a backend and [atom-ide-ui](https://atom.io/packages/atom-ide-ui) as a frontend.
86
+
87
+
```sh
88
+
apm-nightly install atom-ide-ui linter-eslint
89
+
```
90
+
91
+
### Coverage
92
+
93
+
Code coverage by our specs is measured by [istanbul](https://istanbul.js.org/) and reported to [Coveralls](https://coveralls.io/github/atom/github?branch=master). Links to coverage information will be available in a pull request comment and a status check. While we don't _enforce_ full coverage, we do encourage submissions to not regress our coverage percentage whenever feasible.
94
+
95
+
If you wish to preview coverage data locally, run one of:
96
+
97
+
```sh
98
+
# ASCII table output
99
+
npm run test:coverage:text
100
+
101
+
# HTML document output
102
+
npm run test:coverage:html
103
+
104
+
# lcov output
105
+
npm run test:coverage
106
+
```
107
+
108
+
Generating lcov data allows you to integrate an Atom package like [atom-lcov](https://atom.io/packages/atom-lcov) to see covered and uncovered source lines and branches with editor annotations.
109
+
110
+
If you prefer the graphical test runner, it may be altered to generate lcov coverage data by adding a command like the following to your `init.js` file:
To accelerate its launch time, Atom constructs a [v8 snapshot](http://blog.atom.io/2017/04/18/improving-startup-time.html) at build time that may be loaded much more efficiently than parsing source code from scratch. As a bundled core package, the GitHub package is included in this snapshot. A tool called [electron-link](https://github.com/atom/electron-link) is used to pre-process all bundled source to prepare it for snapshot generation. This does introduce some constraints on the code constructs that may be used, however. While uncommon, it pays to be aware of the limitations this introduces.
125
+
126
+
The most commonly encountered hindrance is that you cannot reference DOM primitives, native modules, or Atom API constructs _at module require time_ - in other words, with a top-level `const` or `let` expression, or a function or the constructor of a class invoked from one:
127
+
128
+
```js
129
+
import {TextBuffer} from'atom';
130
+
131
+
// Error: static reference to DOM methods
132
+
constnode=document.createElement('div')
133
+
134
+
// Error: indirect static reference to core Atom API
135
+
functionmakeTextBuffer() {
136
+
returnnewTextBuffer({text:'oops'});
137
+
}
138
+
consttheBuffer=newTextBuffer();
139
+
140
+
// Error: static reference to DOM in class definition
141
+
classSomeElementextendsHTMLElement {
142
+
// ...
143
+
}
144
+
```
145
+
146
+
Introducing new third-party npm package dependencies (as non-`devDependencies`) or upgrading existing ones can also result in snapshot regressions, because authors of general-purpose npm packages, naturally, don't consider this :wink:
147
+
148
+
We do have a CI job in our test matrix that verifies that a electron-link and snapshot creation succeed for each commit.
149
+
150
+
If any of these situations are _unavoidable_, individual modules _may_ be excluded from the snapshot generation process by adding them to the exclusion lists [within Atom's build scripts](https://github.com/atom/atom/blob/d29bb96c8ea09e5d9af2eb5b060227d11be2b92a/script/lib/generate-startup-snapshot.js#L27-L68) and [the GitHub package's snapshot testing script](https://github.com/atom/github/blob/3703f571e41f22c7076243abaab1a610b5b37647/test/generation.snapshot.js#L38-L43). Use this solution very sparingly, though, as it impacts Atom's startup time and adds confusion.
8
151
9
152
## Technical contribution tips
10
153
154
+
### More information
155
+
156
+
We have a growing body of documentation about the architecture and organization of our source code in the [`docs/` subdirectory](/docs) of this repository. Check there for detailed technical dives into the layers of our git integration, our React component architecture, and other information.
157
+
158
+
We use the following technologies:
159
+
160
+
*[Atom API](https://atom.io/docs) to interact with the editor.
161
+
*[React](https://reactjs.org/) is the framework that powers our view implementation.
162
+
* We interact with GitHub via its [GraphQL](https://graphql.org/) API.
163
+
*[Relay](https://github.com/facebook/relay) is a layer of glue between React and GraphQL queries that handles responsibilities like query composition and caching.
164
+
* Our tests are written with [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/)[_(with the "assert" style)_](https://www.chaijs.com/api/assert/). We also use [Enzyme](https://airbnb.io/enzyme/) to assert against React behavior.
165
+
* We use a [custom Babel 6 transpiler pipeline](https://github.com/atom/atom-babel6-transpiler) to write modern source with JSX, `import` statements, and other constructs unavailable natively within Atom's Node.js version.
166
+
11
167
### Updating the GraphQL Schema
12
168
13
-
This project uses [Relay](https://github.com/facebook/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
169
+
Relay includes 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
14
170
15
171
```bash
16
172
GITHUB_TOKEN=abcdef0123456789 npm run fetch-schema
@@ -22,14 +178,6 @@ Please check in the generated `graphql/schema.graphql`.
22
178
23
179
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.
24
180
25
-
## Testing
26
-
27
-
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.
28
-
29
-
To re-run tests, you can refresh that window by pressing `Cmd + R` in DevTools.
30
-
31
-
You can also run them on the command line with `npm run test`.
32
-
33
181
### Async Tests
34
182
35
183
Sometimes it's necessary to test async operations. For example, imagine the following test:
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'.
67
215
68
216
When writing tests that depend on values that get set asynchronously, prefer `assert.async.x(...)` over other forms.
69
-
70
-
## Living on the edge
71
-
72
-
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.
73
-
74
-
1.[Build Atom from master](https://github.com/atom/atom/tree/master/docs/build-instructions) frequently if you can. This will help us notice any changes in Atom core that cause regressions.
75
-
2. Install the GitHub package from its git URL:
76
-
77
-
```sh
78
-
$ apm install atom/github
79
-
```
80
-
81
-
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 :wink:
82
-
3. Link your GitHub package source in dev mode:
83
-
84
-
```sh
85
-
# In the root directory of your atom/github clone
86
-
$ apm link --dev .
87
-
```
88
-
89
-
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.
0 commit comments