| 1 |
# Contributing |
| 2 |
|
| 3 |
So you want to contribute to the Importer? Fantastic! There are a few rules you'll need to follow for all contributions. |
| 4 |
|
| 5 |
(There are always exceptions to these rules. :) ) |
| 6 |
|
| 7 |
## Process |
| 8 |
|
| 9 |
1. Ideally, start with an issue to check the need for a PR. It's possible that a feature may be rejected at an early stage, and it's better to find out before you write the code. |
| 10 |
2. Write the code. Small, atomic commits are preferred. Explain the motivation behind the change when needed. |
| 11 |
3. File a PR. If it isn't ready for merge yet, note that in the description. If your PR closes an existing issue, add "fixes #xxx" to the message, so that the issue will be closed when the PR is merged. |
| 12 |
4. If needed, iterate on the code until it is ready. This includes adding unit tests. When you're ready, comment that the PR is complete. |
| 13 |
5. A committer will review your code and offer you feedback. |
| 14 |
6. Update with the feedback as necessary. |
| 15 |
7. PR will be merged. |
| 16 |
|
| 17 |
Notes: |
| 18 |
|
| 19 |
* All code needs to go through peer review. Committers may not merge their own PR. |
| 20 |
* PRs should **never be squashed or rebased**. This includes when merging. Keeping the history is important for tracking motivation behind changes later. |
| 21 |
|
| 22 |
## Best Practices |
| 23 |
|
| 24 |
All code in the Importer must be compatible with PHP 5.2. Treat this code as if it were part of WordPress core, and apply the [](https://make.wordpress.org/core/handbook/best-practices/same best practices](https://make.wordpress.org/core/handbook/best-practices/](https://make.wordpress.org/core/handbook/best-practices/). |
| 25 |
|
| 26 |
### Commit Messages |
| 27 |
|
| 28 |
Commit messages should follow the [](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.htmlgeneral git best practices](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html): |
| 29 |
|
| 30 |
``` |
| 31 |
Capitalized, short (50 chars or less) summary |
| 32 |
|
| 33 |
More detailed explanatory text, if necessary. Wrap it to about 72 |
| 34 |
characters or so. In some contexts, the first line is treated as the |
| 35 |
subject of an email and the rest of the text as the body. The blank |
| 36 |
line separating the summary from the body is critical (unless you omit |
| 37 |
the body entirely); tools like rebase can get confused if you run the |
| 38 |
two together. |
| 39 |
|
| 40 |
Write your commit message in the imperative: "Fix bug" and not "Fixed bug" |
| 41 |
or "Fixes bug." This convention matches up with commit messages generated |
| 42 |
by commands like git merge and git revert. |
| 43 |
|
| 44 |
Further paragraphs come after blank lines. |
| 45 |
|
| 46 |
- Bullet points are okay, too |
| 47 |
|
| 48 |
- Typically a hyphen or asterisk is used for the bullet, followed by a |
| 49 |
single space, with blank lines in between, but conventions vary here |
| 50 |
|
| 51 |
- Use a hanging indent |
| 52 |
``` |
| 53 |
|
| 54 |
There is no need to reference issues inside commits, as all interaction with issues is handled via pull requests. |
| 55 |
|
| 56 |
|
| 57 |
## Coding Style |
| 58 |
|
| 59 |
The coding style should match [](https://make.wordpress.org/core/handbook/coding-standards/php/the WordPress coding standards](https://make.wordpress.org/core/handbook/coding-standards/php/](https://make.wordpress.org/core/handbook/coding-standards/php/). |
| 60 |
|
| 61 |
|
| 62 |
## Unit Tests |
| 63 |
|
| 64 |
PRs should include unit tests for any changes. These are written in PHPUnit, and should be added to the file corresponding to the class they test (that is, tests for `class-wxr-importer.php` would be in `tests/test-wxr-importer.php`). |
| 65 |
|
| 66 |
Where possible, features should be unit tested. The eventual aim is to have >90% coverage. |
| 67 |
|
| 68 |
<!-- |
| 69 |
We aim for >90% coverage at all times. The master branch may drop below 90% if features are merged independently of their tests, but there is a hard limit of 85%. Release versions must have >90% coverage. |
| 70 |
|
| 71 |
For complex features by third-parties, PRs may be merged that drop coverage below the 90% threshold, with the intent of increasing tests back up in a subsequent PR. |
| 72 |
--> |
| 73 |
|
| 74 |
|
| 75 |
## Licensing |
| 76 |
|
| 77 |
By contributing code to this repository, you agree to license your code for use under the [](https://github.com/humanmade/WordPress-Importer/blob/master/LICENSEGPL License](https://github.com/humanmade/WordPress-Importer/blob/master/LICENSE](https://github.com/humanmade/WordPress-Importer/blob/master/LICENSE). |
| 78 |
|
