|
| 1 | +# JDB - Contributing Guide |
| 2 | + |
| 3 | +- [Issues](#issues) |
| 4 | +- [Pull Request - Guide](#pull-request-guide) |
| 5 | +- [Setting up development environment](#development-setup) |
| 6 | +- [Code style guide](#code-style) |
| 7 | +- [Documentation standard](#doc-standard) |
| 8 | +- [Jar generation](#jar-generation) |
| 9 | +- [Creating branches](#new-branch) |
| 10 | +- [Creating tags](#new-tag) |
| 11 | + |
| 12 | + |
| 13 | +## <a name="issues"></a> Issues |
| 14 | + |
| 15 | +- If there is a problem or question while editing the project, create an [issue](https://github.com/wniemiec-component-java/junit4-runner/pulls) detailing the problem or question. |
| 16 | + |
| 17 | + |
| 18 | +## <a name="pull-request-guide"></a> Pull Request - Guide |
| 19 | + |
| 20 | +### Branch |
| 21 | +- If the changes made do not change the structure of the application or the way to use any functionality, use the current branch; otherwise, [creates a new branch](#new-branch) in the following format: |
| 22 | + |
| 23 | +> If the current branch is `N.x`, the new branch should be called `(N + 1).x` (without parentheses), where N is a number |
| 24 | +
|
| 25 | +<b>Attention:</b> Do not make any changes using the `master` branch, as it will be the result of the merge with the latest version released. |
| 26 | + |
| 27 | +### Tag |
| 28 | +- Always create a tag before creating a pull request |
| 29 | +- Only create the tag at the end of your changes |
| 30 | +- only one tag per pull request must be created |
| 31 | +- Choose a different tag from the current tag. If the current tag is X.Y.Z, where X, Y and Z are numbers, [create a new tag](#new-tag) using the following criteria: |
| 32 | + - If the changes made are minor, that is, small modifications that do not change the way of using a feature or even for bug fixes, create the tag `X.Y.(Z + 1)` (without parentheses) |
| 33 | + - If new features are added, create the `X.(Y + 1).0` tag (without parentheses) |
| 34 | + - If the way of using one or more features is changed, or even if a feature is deleted, create a new branch with the name `(X + 1).x` and create a new tag with the name `(X + 1).0.0` (without parentheses) |
| 35 | + |
| 36 | +<b>Attention:</b> Tag creation should be `Annotated Tags` type. |
| 37 | + |
| 38 | + |
| 39 | +- Released versions should be placed in the `dist/X.Y` directory, where X and Y are the released version numbers |
| 40 | +- Try whenever possible to add tests on each added feature. If a feature is edited, make sure the tests related to it continue to work. |
| 41 | +- Before adding a new functionality, it is recommended to create an issue describing the new functionality and a justification of why it would be useful to the application. |
| 42 | + |
| 43 | +If the contribution is to correct a bug, the commit should be: `bug fix # xyzw`, where #xyzw is the issue id that quotes the bug. If not, the commit should be `bug fix <DESCRIPTION>`, where \<DESCRIPTION\> is a brief description of the bug that has been fixed. |
| 44 | + |
| 45 | +### <a name="pull-request-submit"></a> Pull request submit |
| 46 | +After making changes to the project, create a pull request with the project you have modified. Try to add a detailed description of what you changed from the original project. Avoid changing the structure of the project as much as possible to avoid breaking code. |
| 47 | + |
| 48 | + <b> Attention: </b> Before making the pull request, make sure that: |
| 49 | + * Generate the version jar in the following format: `junit4-runner-X.Y.Z.jar`, where X, Y and Z are the numbers corresponding to the tag that will contain the changes made; |
| 50 | + * Document the changes according to the [documentation standard mentioned above](#doc-standard). |
| 51 | + |
| 52 | +## <a name="development-setup"></a> Setting up development environment |
| 53 | + |
| 54 | +To work on the project, any IDE with support for JDB can be used (to execute the project tests). |
| 55 | + |
| 56 | +### <a name="output-dir"></a>Output directory |
| 57 | +The output directory of the project, that is, the directory where the compiled files will be placed must be `bin`, which must be at the root of the project. It is worth mentioning that this directory should not be submitted to the repository (`.gitignore` will ignore this directory). |
| 58 | + |
| 59 | +## <a name="code-style"></a>Code style guide |
| 60 | +The project uses the [code style recommended by Oracle](https://www.oracle.com/java/technologies/javase/codeconventions-contents.html), with one exception: structures `if-then-else`, `try-catch-finally` and the like should not have a closed curly bracket (`}`) to the left of the keyword. |
| 61 | + |
| 62 | +### Example |
| 63 | +#### Good |
| 64 | +<pre> |
| 65 | +if (x == 2) { |
| 66 | + return "two"; |
| 67 | +} |
| 68 | +else if (x == 3) { |
| 69 | + return "three" |
| 70 | +} |
| 71 | +</pre> |
| 72 | + |
| 73 | +#### Bad |
| 74 | +<pre> |
| 75 | +if (x == 2) { |
| 76 | + return "two"; |
| 77 | +} else if (x == 3) { |
| 78 | + return "three" |
| 79 | +} |
| 80 | +</pre> |
| 81 | + |
| 82 | + |
| 83 | +## <a name="doc-standard"></a>Documentation standard |
| 84 | +All classes, public methods and some variables use [javadoc](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html) to explain its functionality. |
| 85 | + |
| 86 | + |
| 87 | +### <a name="doc-standard-class-enum"></a>Classes, inner classes and enumerations |
| 88 | +Classes should use the following pattern: |
| 89 | + |
| 90 | +<pre> |
| 91 | +/** |
| 92 | + * Class description. |
| 93 | + * |
| 94 | + * @since A.B.C |
| 95 | + */ |
| 96 | +</pre> |
| 97 | + |
| 98 | +Where X, Y and Z are numbers relative to the version of the application in which the class was last modified and A, B and C identify the version of the application in which the class was created. The annotation is separated from the content with 2 tabs. In addition, internally, the class should be divided into sections, which are identified with the following pattern: |
| 99 | + |
| 100 | +<pre> |
| 101 | +//------------------------------------------------------------------------- |
| 102 | +// [section_name] |
| 103 | +//------------------------------------------------------------------------- |
| 104 | +</pre> |
| 105 | + |
| 106 | +Where [section_name] can be: |
| 107 | +* Attributes |
| 108 | +* Constructor(s) |
| 109 | +* Methods |
| 110 | +* Getters |
| 111 | +* Getters & Setters |
| 112 | +* Setters |
| 113 | +* Initialization block |
| 114 | +* Tests |
| 115 | +* Test hooks |
| 116 | +* Serialization and deserialization methods |
| 117 | +* Enumerations |
| 118 | +* Inner classes |
| 119 | + |
| 120 | + |
| 121 | +### <a name="doc-standard-methods"></a> Methods |
| 122 | +Public methods must be documented using javadoc. |
| 123 | + |
| 124 | +## Appendix |
| 125 | + |
| 126 | +### <a name="new-branch"></a> Creating branches |
| 127 | +Create a new branch: |
| 128 | + |
| 129 | +<pre> |
| 130 | +git checkout -b branch_name |
| 131 | +</pre> |
| 132 | + |
| 133 | +Add to the remote repository: |
| 134 | + |
| 135 | +<pre> |
| 136 | +git push -u origin branch_name |
| 137 | +</pre> |
| 138 | + |
| 139 | +#### Example |
| 140 | +<pre> |
| 141 | +git checkout -b v1.x |
| 142 | +git push -u origin v1.x |
| 143 | +</pre> |
| 144 | + |
| 145 | +See more [here](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging). |
| 146 | + |
| 147 | +### <a name="new-tag"></a> Creating tags |
| 148 | +<pre> |
| 149 | +git tag -a tag_name -m description |
| 150 | +</pre> |
| 151 | + |
| 152 | +Add to the remote repository: |
| 153 | + |
| 154 | +<pre> |
| 155 | +git push -u origin tag_name |
| 156 | +</pre> |
| 157 | + |
| 158 | +#### Example |
| 159 | +<pre> |
| 160 | +git tag -a v1.0.1 -m "Performance improvement" |
| 161 | +git push -u origin v1.0.1 |
| 162 | +</pre> |
| 163 | + |
| 164 | +See more [here](https://git-scm.com/book/en/v2/Git-Basics-Tagging). |
0 commit comments