Adds step do run smoke tests
[pixelated-user-agent.git] / CONTRIBUTING.md
1 # How to contribute
2
3 Here's the brief:
4
5 * We welcome contributions of all kinds, including but not limited to features, bug fixes, quality assurance, documentation, security review or asking questions
6 * Pull requests are based off, integrated into & rebased against master
7 * Write automated tests, ideally using TDD. CI needs to be green in order to merge.
8 * [Waffle](https://waffle.io/pixelated/pixelated-user-agent) board for ready to play work
9 * Contact us for questions & suggestions:
10   * IRC: #pixelated @ chat.freenode.org ([join via webchat](https://webchat.freenode.net/))
11   * Email: [team@pixelated-project.org](mailto:team@pixelated-project.org)
12   * Twitter: [@pixelatedteam](https://twitter.com/pixelatedteam)
13
14
15   This document outlines our way of working, gives hints and outlines the steps to make your contribution to Pixelated as smooth as possible. You're not required to read this before getting started. We're explaining the way we work to make sure you're having a good experience and can make best use of the time you're contributing to our project.
16
17 ## Contributions steps
18
19 This is the lifecycle of a contribution. See our [README](README.md) for details on how to set up your development environment.
20
21 We follow a simplified fork + pull request workflow:
22
23 * To start, fork this repository and create a branch that's based off the latest commit in the `master` branch
24 * Implement the change
25 * Send a pull request against the master branch. Please make sure the automated tests are passing, as indicated by GitHub on the pull requests.
26 * Please keep your feature branch updated. Rebase your branch against upstream changes on the master branch, resolve any conflicts and make sure the tests are staying green.
27 * Your pull request will be reviewed and merged
28
29 ### What to work on
30
31 Our [Kanban board "Waffle"](https://waffle.io/pixelated/pixelated-user-agent) provides an overview of issues that are ready to play or awaiting QA. If you're just getting familiar with Pixelated, see the [issues labeled 'Volunteer Task'](https://github.com/pixelated/pixelated-user-agent/labels/Volunteer%20task).
32
33 Generally, all issues that have no user assigned are awaiting work and free to play. If you want to make sure, or you think it will take more than a couple of days to complete your work, please reach out to us using the contact info above.
34
35 ### Guidelines
36
37 When implementing your change, please follow this advice:
38
39 * Your change should be described in an issue, or latest in the pull request description.
40 * For bugs, please describe, in an issue or pull request:
41   1. Steps to reproduce the behavior
42   2. Expected behavior
43   3. Actual behavior. Please also include as much meta-information as reasonable, e.g. time & date, software version etc.
44 * Pull requests need not to be finished work only; you can also submit changes in consecutive Pull Requests as long as CI stays green. Also, please send a PR with the intention of discussion & feedback. Please mark those Pull Requests appropriately.
45 * We review your pull request. This review is prioritised and done as part of our priotisation. During this time, we ask you to keep it up to date by frequently rebasing against master
46
47 ### Review Criteria
48
49 When reviewing your contribution, we apply the following criteria:
50
51 * Test must be green. This usually includes an automatic check of the style guide using e.g. pep8 or jshint. All tests should be executed locally before you push, as well as on CI. If you struggle to reproduce a failure on CI locally, please notify us on IRC so we can resolve the issue.
52 * Your change should be in-line with Pixelated's direction. Chances that it is are good if, in descending priority:
53   * It is described by an issue that is labelled as 'ready'
54   * It is described by an issue that is labelled as 'backlog'
55   * You've fixed a bug for which no issue existed yet, but described it in the pull request as explained in the section *Steps*
56   * You've implemented a feature for which no issue existed yet. While we don't require up-front consensus, we strongly encourage you to describe feature suggestions in issues to get feedback before you spent significant time on implementation.
57 * We won't tolerate abusive, exploitative or harassing behavior in every context of our project and refuse collaboration with any individual who exposes such behavior.
58
59 ## Types of contributions
60
61 Pixelated evolves upon the source code it's made of. This evolution is fueled by a variety of tasks; some of which require developing source code, some of which do not.
62
63 Contributions we appreciate:
64
65 * Features: New functionality is described in issues in the form of a user story to capture the end-user benefit.
66 * Bug fixes: Things go wrong from time to time.
67 * Quality Assurance: While every software change should be covered by automated tests, there are certain types of errors that are best spotted by a human. We apply QA to dev-complete changes.
68 * Documentation: Feedback & improvements of our guides & tutorial copywritings.
69 * Security review
70 * Translations
71 * Asking questions on IRC
72
73 ## Translating UI
74
75 Anyone can contribute with Pixelated translating our user interface and making it accessible for more people. All the translation work is managed at [Transifex](https://www.transifex.com). Follow the steps below to start contributing:
76
77 * Sign up at [Transifex](https://www.transifex.com) and visit our [Pixelated project](https://www.transifex.com/pixelated/) page.
78 * On the project page, choose the language you want to work on. If the language doesn’t exist yet you can request a new language by clicking on the “Request language”.
79 * Then, click the “Join this Team” button to become a member of this team. You will be accepted as soon as possible.
80
81 We strongly recommend you read [Transifex User Guide](http://docs.transifex.com/) if it's the first time using this tool.
82
83 More information see [Managing Translations page](https://github.com/pixelated/pixelated-user-agent/wiki/Managing-translations)
84
85 ## ThoughtWorks' role
86
87 ThoughtWorks seeds the community that builds pixelated. We seed the development, investing our own resources: We provide a team of 10+ software delivery experts to lay the foundation for the project. We use our network and contacts to approach customers and users.
88
89 ThoughtWorks started building Pixelated because it is right. In combining our passion for defending a free internet and our capability to deliver software, we build software to counter widespread mass surveillance of email communication.
90
91 It is not ThoughWorks' goal to make money from Pixelated. The reasons are multiple, but at the end of the day, we believe that our goals of mass adoption and decentralization can best be achieved if Pixelated puts end users and providers before a revenue stream.