|
| 1 | +# Contributing to the project |
| 2 | +The project is released under the [MIT](http://opensource.org/licenses/MIT) license. |
| 3 | +If you would like to contribute something, or simply want to hack the code, this document should |
| 4 | +help you get started. |
| 5 | + |
| 6 | +## Reporting bugs and suggesting enhancements |
| 7 | +If you find a bug, please submit an [issue](https://github.com/gazbert/java-design-patterns/issues). Try to |
| 8 | +provide enough information for someone else to reproduce it. Equally, submit an issue if you want |
| 9 | +to create a new feature or enhance an existing one - refactoring, improving Javadoc, and boosting |
| 10 | +test coverage is always welcome! |
| 11 | + |
| 12 | +One of the project's maintainers should respond to your issue within a few days... if not, bump the |
| 13 | +issue and request that it be reviewed. |
| 14 | + |
| 15 | +## Contributor workflow |
| 16 | + |
| 17 | +Review the [issues list](https://github.com/gazbert/java-design-patterns/issues) and find something that |
| 18 | +interests you. It is wise to start with something relatively straightforward and achievable. |
| 19 | +Usually there will be a comment in the issue that indicates whether someone has already |
| 20 | +self-assigned it. If no one has already taken the issue, then add a comment assigning the issue to |
| 21 | +yourself, e.g. ```I'm working on this issue because I love writing Javadoc...``` |
| 22 | + |
| 23 | +Please be considerate and rescind the offer in a comment if you cannot finish in a reasonable time, |
| 24 | +or add a new comment stating that you're still actively working on the issue and need a little |
| 25 | +more time. |
| 26 | + |
| 27 | +We are using the [GitHub Flow](https://guides.github.com/introduction/flow/) process to manage |
| 28 | +code contributions. If you are unfamiliar, please review that link before proceeding. |
| 29 | +To work on something, whether a new feature or a bug fix: |
| 30 | + |
| 31 | +1. [Fork](https://help.github.com/articles/fork-a-repo/) the repo. |
| 32 | +2. Clone it locally: |
| 33 | + |
| 34 | + ``` |
| 35 | + git clone https://github.com/<your-id>/java-design-patterns.git |
| 36 | + ``` |
| 37 | +3. Add the upstream repository as a remote: |
| 38 | + ``` |
| 39 | + git remote add upstream https://github.com/gazbert/java-design-patterns.git |
| 40 | + ``` |
| 41 | +Make sure you keep your forked repo [up-to-date](https://help.github.com/articles/syncing-a-fork/) |
| 42 | +with the upstream repository. |
| 43 | + |
| 44 | +4. Create a meaningful-named branch off of your cloned fork - full details |
| 45 | + [here](https://git-scm.com/docs/git-checkout). |
| 46 | + |
| 47 | + ``` |
| 48 | + cd bxbot |
| 49 | + git checkout -b my-new-feature-or-bugfix-branch |
| 50 | + ``` |
| 51 | +5. Write some code! Commit to that branch locally, and regularly push your work to the same |
| 52 | + branch on the server. Commit messages must have a short description no longer than 50 characters |
| 53 | + followed by a blank line and a longer, more descriptive message that includes reference to |
| 54 | + issue(s) being addressed so that they will be automatically closed on a merge e.g. |
| 55 | + ```Closes #1234``` or ```Fixes #1234``` - see |
| 56 | + [here](https://help.github.com/articles/closing-issues-via-commit-messages/) for more details. |
| 57 | + When writing a commit message please follow |
| 58 | + [these conventions](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). |
| 59 | + |
| 60 | +6. Any code changes that affect documentation (e.g. README.MD) should be accompanied by |
| 61 | + corresponding changes (or additions) to the documentation and tests. This will ensure that if |
| 62 | + the merged PR is reversed, all traces of the change will be reversed as well. |
| 63 | + |
| 64 | +7. When you're done, make sure your build is green and create a |
| 65 | + [Pull Request (PR)](https://help.github.com/articles/using-pull-requests/) to submit your changes. |
| 66 | + |
| 67 | + |
| 68 | +After your PR has been reviewed and signed off, a maintainer will merge it into |
| 69 | +the master branch. |
| 70 | + |
| 71 | +## Code conventions and housekeeping |
| 72 | + |
| 73 | +The following conventions should be followed: |
| 74 | + |
| 75 | +* Make sure all new `.java` files to have a simple Javadoc class comment with at least an |
| 76 | + `@author` tag identifying you, and preferably at least a paragraph on what the class is for. |
| 77 | + All public API methods should have detailed Javadoc describing the contract and what they do. |
| 78 | +* Add the MIT license header comment to all new `.java` files - copy from existing files in the |
| 79 | + project. |
| 80 | +* Did we mention tests? All code changes should be accompanied by new or modified tests. |
| 81 | + Someone has to do it... |
| 82 | +* Add yourself as an `@author` to the `.java` files that you modify substantially |
| 83 | + (more than cosmetic changes). |
| 84 | +* In general commits should be atomic and diffs should be easy to read. For this reason do not mix |
| 85 | + any formatting fixes or code moves with actual code changes. |
| 86 | +* We use the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) for |
| 87 | + formatting our code. You can download the style template for your IDE from |
| 88 | + [here](https://github.com/google/styleguide). If you use IntelliJ, there's also a handy |
| 89 | + [Google plugin](https://plugins.jetbrains.com/plugin/8527-google-java-format) for formatting your |
| 90 | + code. |
0 commit comments