Remove old architecture diagram
[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 * Feel free to review the repository's issues for ideas on what to work on
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 ### Getting acquainted with the code
30
31 If you're not sure how to start development, check out [our short guide](https://github.com/pixelated/pixelated-user-agent/wiki/Starting-Development) on how to start getting to know the code.
32
33 ### What to work on
34
35 Our Github provides an overview of issues that are ready to play. If you're just getting familiar with Pixelated, see the [issues labeled 'Volunteer Task'](https://github.com/pixelated/pixelated-user-agent/labels/Volunteer%20task).
36
37 Generally, all issues that have no user assigned are awaiting work and free to play.
38
39 ### Guidelines
40
41 When implementing your change, please follow this advice:
42
43 * Your change should be described in an issue, or latest in the pull request description.
44 * For bugs, please describe, in an issue or pull request:
45   1. Steps to reproduce the behavior
46   2. Expected behavior
47   3. Actual behavior. Please also include as much meta-information as reasonable, e.g. time & date, software version etc.
48 * 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.
49 * 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
50
51 ### Review Criteria
52
53 When reviewing your contribution, we apply the following criteria:
54
55 * 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 outlined in the [wiki](https://github.com/pixelated/pixelated-user-agent/wiki/Running-Tests), 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.
56 * Your change should be in line with Pixelated's direction. Chances that it is are good if, in descending priority:
57   * It is described by an issue that is labelled as 'ready'
58   * It is described by an issue that is labelled as 'backlog'
59   * You've fixed a bug for which no issue existed yet, but described it in the pull request as explained in the section *Steps*
60   * 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.
61 * 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.
62
63 ## Types of contributions
64
65 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.
66
67 Contributions we appreciate:
68
69 * Features: New functionality is described in issues in the form of a user story to capture the end-user benefit.
70 * Bug fixes: Things go wrong from time to time.
71 * 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.
72 * Documentation: Feedback & improvements of our guides & tutorial copywritings.
73 * Security review
74 * Translations
75
76 ## Translating UI
77
78 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:
79
80 * Sign up at [Transifex](https://www.transifex.com) and visit our [Pixelated project](https://www.transifex.com/pixelated/) page.
81 * 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”.
82 * Then, click the “Join this Team” button to become a member of this team. You will be accepted as soon as possible.
83
84 We strongly recommend you read [Transifex User Guide](http://docs.transifex.com/) if it's the first time using this tool.
85
86 More information see [Managing Translations page](https://github.com/pixelated/pixelated-user-agent/wiki/Managing-translations)