Source code

Revision control

Other Tools

1
# Contributing to Activity Stream
2
3
Activity Stream is an enhancement to the functionality of Firefox's about:newtab page. We welcome new 'streamers' to contribute to the project!
4
5
## Where to ask questions
6
7
- Most of the core dev team can be found on the `#activity-stream` channel on `irc.mozilla.org`.
8
You can also direct message the core team (`dmose`, `emtwo`, `jkerim`, `k88hudson`, `Mardak`, `nanj`, `r1cky`, `ursula`, `andreio`)
9
or our manager (`tspurway`)
10
- Slack channel (staff only): #activitystream
12
- File issues/questions on Github: https://github.com/mozilla/activity-stream/issues. We typically triage new issues every Monday.
13
14
## Architecture ##
15
16
Activity Stream is a Firefox system add-on. One of the cool things about Activity Stream is that the
18
is written using [ReactJS](https://facebook.github.io/react/). This makes it an awesome project for React hackers to contribute to!
19
20
## Finding Bugs, Filing Tickets, Earning Karma ##
21
22
Activity Stream lives on [GitHub](https://github.com/mozilla/activity-stream), but you already knew that! If you've found
23
a bug, or have a feature idea that you you'd like to see in Activity Stream, follow these simple guidelines:
24
- Pick a thoughtful and terse title for the issue (ie. *not* Thing Doesn't Work!)
25
- Make sure to mention your Firefox version, OS and basic system parameters (eg. Firefox 49.0, Windows XP, 512KB RAM)
26
- If you can reproduce the bug, give a step-by-step recipe
27
- Include [stack traces from the console(s)](https://developer.mozilla.org/en-US/docs/Mozilla/Debugging/Debugging_JavaScript) where appropriate
28
- Screenshots welcome!
29
- When in doubt, take a look at some [existing issues](https://github.com/mozilla/activity-stream/issues) and emulate
30
31
## Take a Ticket, Hack some Code ##
32
33
If you are new to the repo, you might want to pay close attention to [`Good first bug`](https://github.com/mozilla/activity-stream/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+first+bug%22),
37
typically a great way to get started. You might see a bug that is not yet assigned to anyone, or start a conversation with
38
an engineer in the ticket itself, expressing your interest in taking the bug. If you take the bug, someone will set
39
the ticket to [`Assigned to Contributor`](https://github.com/mozilla/activity-stream/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22Assigned%20to%20contributor%22%20), which is a way we can be pro-active about helping you succeed in fixing the bug.
40
41
When you have some code written, you can open up a [Pull Request](#pull-requests), get your code [reviewed](#code-reviews), and see your code merged into the Activity Stream codebase.
42
43
If you are thinking about contributing on a longer-term basis, check out the section on [milestones](#milestones) and [priorities](#priorities)
44
to get a sense of how we plan and prioritize work.
45
46
## Setting up your development environment
47
48
Check out [this guide](docs/v2-system-addon/1.GETTING_STARTED.md) on how to install dependencies, get set up, and run tests.
49
50
## Pull Requests ##
51
52
You have identified the bug, written code and now want to get it into the main repo using a [Pull Request](https://help.github.com/articles/about-pull-requests/).
53
54
All code is added using a pull request against the `master` branch of our repo. Before submitting a PR, please go through this checklist:
55
- all [unit tests](docs/v2-system-addon/unit_testing_guide.md) must pass
56
- if you haven't written unit tests for your patch, eyebrows will be curmudgeonly furrowed (write unit tests!)
57
- if your pull request fixes a particular ticket (it does, right?), please use the `fixes #nnn` github annotation to indicate this
58
- please add a `PR / Needs review` tag to your PR (if you have permission). This starts the code review process. If you cannot add a tag, don't worry, we will add it during triage.
59
- if you can pick a module owner to be your reviewer by including `r? @username` in the comment (if not, don't worry, we will assign a reviewer)
60
- make sure your PR will merge gracefully with `master` at the time you create the PR, and that your commit history is 'clean'
61
62
### Setting up pre-push hooks
63
64
If you contribute often and would like to set up a pre-push hook to always run `npm lint` before you push to Github,
65
you can run the following from the root of the activity-stream directory:
66
67
```
68
cp hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
69
```
70
71
Your hook should now run whenever you run `git push`. To skip it, use the `--no-verify` option:
72
73
```
74
git push --no-verify
75
```
76
77
78
## Code Reviews ##
79
80
You have created a PR and submitted it to the repo, and now are waiting patiently for you code review feedback. One of the projects
81
module owners will be along and will either:
82
- make suggestions for some improvements
83
- give you an `R+` in the comments section, indicating the review is done and the code can be merged
84
85
Typically, you will iterate on the PR, making changes and pushing your changes to new commits on the PR. When the reviewer is
86
satisfied that your code is good-to-go, you will get the coveted `R+` comment, and your code can be merged. If you have
87
commit permission, you can go ahead and merge the code to `master`, otherwise, it will be done for you.
88
89
Our project prides itself on it's respectful, patient and positive attitude when it comes to reviewing contributor's code, and as such,
90
we expect contributors to be respectful, patient and positive in their communications as well. Let's be friends and learn
91
from each other for a free and awesome web!
92
94
95
## Git Commit Guidelines ##
96
97
We loosely follow the [Angular commit guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#type) of `<type>(<scope>): <subject>` where `type` must be one of:
98
99
* **feat**: A new feature
100
* **fix**: A bug fix
101
* **docs**: Documentation only changes
102
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
103
semi-colons, etc)
104
* **refactor**: A code change that neither fixes a bug or adds a feature
105
* **perf**: A code change that improves performance
106
* **test**: Adding missing tests
107
* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
108
generation
109
110
### Scope
111
The scope could be anything specifying place of the commit change. For example `timeline`,
112
`metadata`, `reporting`, `experiments` etc...
113
114
### Subject
115
The subject contains succinct description of the change:
116
117
* use the imperative, present tense: "change" not "changed" nor "changes"
118
* don't capitalize first letter
119
* no dot (.) at the end
120
121
### Body
122
In order to maintain a reference to the context of the commit, add
123
`fixes #<issue_number>` if it closes a related issue or `issue #<issue_number>`
124
if it's a partial fix.
125
126
You can also write a detailed description of the commit:
127
Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes"
128
It should include the motivation for the change and contrast this with previous behavior.
129
130
### Footer
131
The footer should contain any information about **Breaking Changes** and is also the place to
132
reference GitHub issues that this commit **Closes**.
133
134
## Milestones ##
135
136
All work on Activity Stream is broken into two week iterations, which we map into a GitHub [Milestone](https://github.com/mozilla/activity-stream/milestones). At the beginning of the iteration, we prioritize and estimate tickets
137
into the milestone, attempting to figure out how much progress we can make during the iteration.
138
139
## Priorities ##
140
141
All tickets that have been [triaged](#triage) will have a priority tag of either `P1`, `P2`, `P3`, or `P4` which are highest to lowest
142
priorities of tickets in Activity Stream. We love ticket tags and you might also see `Blocked`, `Critical` or `Chemspill` tags, which
143
indicate our level of anxiety about that particular ticket.
144
145
## Triage ##
146
147
The project team meets weekly (in a closed meeting, for the time being), to discuss project priorities, to triage new tickets, and to
148
redistribute the work amongst team members. Any contributors tickets or PRs are carefully considered, prioritized, and if needed,
149
assigned a reviewer. The project's GitHub [Milestone page](https://github.com/mozilla/activity-stream/milestones) is the best
150
place to look for up-to-date information on project priorities and current workload.
151
152
## License
153
154
MPL 2.0