|
| 1 | +# Contributing to iText |
| 2 | + |
| 3 | +We'd love for you to contribute to our source code and to make iText even better than it is |
| 4 | +today! Here are the guidelines we'd like you to follow: |
| 5 | + |
| 6 | + - [Question or Problem?](#question) |
| 7 | + - [Issues and Bugs](#issue) |
| 8 | + - [New Features](#feature) |
| 9 | + - [Submission Guidelines](#submit) |
| 10 | + - [Coding Rules](#rules) |
| 11 | + - [Commit Message Guidelines](#commit) |
| 12 | + - [Signing the iCLA](#cla) |
| 13 | + - [Contributor Code of Conduct](#coc) |
| 14 | + |
| 15 | + |
| 16 | +## <a name="question">Got a Question or Problem?</a> |
| 17 | + |
| 18 | +If you have questions about how to use iText, please direct these to [StackOverflow][stackoverflow]. |
| 19 | + |
| 20 | +If you are a customer with a [support agreement][support], you also have direct access to our JIRA and our developers. |
| 21 | + |
| 22 | + |
| 23 | +## <a name="issue">Found an Issue?</a> |
| 24 | +If you find a bug in the source code or a mistake in the documentation, you can help us by |
| 25 | +submitting a [Pull Request][pull] with a fix. |
| 26 | + |
| 27 | +**Please see the [Submission Guidelines](#submit) below**. |
| 28 | + |
| 29 | + |
| 30 | +## <a name="feature">Want to implement a Feature?</a> |
| 31 | +If you would like to implement a new feature then consider what kind of change it is: |
| 32 | + |
| 33 | +* **Major Changes** that you wish to contribute to the project should be discussed first so that we can better |
| 34 | +coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully |
| 35 | +accepted into the project. |
| 36 | +* **Small Changes** can be crafted and submitted to the [GitHub Repository][github] as a [Pull Request][pull]. |
| 37 | + |
| 38 | + |
| 39 | +## <a name="submit">Submission Guidelines</a> |
| 40 | + |
| 41 | +### Submitting a Question or an Issue |
| 42 | +Before you submit your question or issue, search [Stack Overflow][stackoverflow], maybe your question was already answered. |
| 43 | + |
| 44 | +If your issue appears to be a bug, and hasn't been reported, ask a question on [Stack Overflow][stackoverflow]. |
| 45 | +Help us to maximize the effort we can spend fixing issues and adding new |
| 46 | +features, by not reporting duplicate issues. Providing the following information will increase the |
| 47 | +chances of your issue being dealt with quickly: |
| 48 | + |
| 49 | +* **[How to ask good questions][good-questions]** |
| 50 | +* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps |
| 51 | +* **Motivation for or Use Case** - explain why this is a bug for you |
| 52 | +* **iText Version(s)** - is it a regression? |
| 53 | +* **Operating System** - is this a problem on Windows or Linux, maybe on Mac? |
| 54 | +* **Reproduce the Error** - provide a [Short, Self Contained, Correct (Compilable), Example][sscce], also known as a [Minimal, Complete, and Verifiable example][mcve]. |
| 55 | +* **Related Issues** - has a similar issue been reported before? |
| 56 | +* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be |
| 57 | + causing the problem (line of code or commit) |
| 58 | +* **Tag the question** - add the tag 'itext' to your question so we can find it. |
| 59 | + |
| 60 | +**If you get help, help others. Good karma rulez!** |
| 61 | + |
| 62 | + |
| 63 | +### Submitting a Pull Request |
| 64 | +Before you submit your pull request consider the following guidelines: |
| 65 | + |
| 66 | +* Search [GitHub][pull] for an open or closed Pull Request |
| 67 | + that relates to your submission. You don't want to duplicate effort. |
| 68 | +* Verify that your proposed change hasn't already been addressed in the develop branch. |
| 69 | +* Don't send a separate pull request for every single file you change. |
| 70 | +* Please sign the [iText Contributor License Agreement (iCLA)](#cla) before sending pull |
| 71 | + requests for any change of more than 20 significant lines of code (we're not counting curly braces and other syntactical sugar). |
| 72 | + We cannot accept code without this agreement. |
| 73 | +* Clone iText to your local machine. |
| 74 | + |
| 75 | + ```shell |
| 76 | + git clone [email protected]:itext/itextpdf.git |
| 77 | + cd itextpdf |
| 78 | + git fetch origin |
| 79 | + git checkout -b develop origin/develop |
| 80 | + ``` |
| 81 | + |
| 82 | +* Make your changes in a new git branch based off the develop branch: |
| 83 | + |
| 84 | + ```shell |
| 85 | + git checkout -b my-fix-branch develop |
| 86 | + ``` |
| 87 | + |
| 88 | +* Create your patch, **including appropriate test cases**. |
| 89 | +* Follow our [Coding Rules](#rules). |
| 90 | +* Run the full iText test suite and ensure that all tests pass. |
| 91 | +* Commit your changes using a descriptive commit message that follows our |
| 92 | + [commit message conventions](#commit-message-format). |
| 93 | + |
| 94 | + ```shell |
| 95 | + git commit -a |
| 96 | + ``` |
| 97 | + Note: the optional commit `-a` command line option will automatically `add` and `rm` edited files. |
| 98 | + |
| 99 | +* Now would be a good time to fix up your commits (if you want or need to) with `git rebase --interactive`. |
| 100 | +* Build your changes locally to ensure all the tests pass. |
| 101 | +* Push your branch to your GitHub account: |
| 102 | + |
| 103 | + ```shell |
| 104 | + git remote add my-remote [email protected]:my-remote/itextpdf.git |
| 105 | + git push my-remote my-fix-branch |
| 106 | + ``` |
| 107 | + |
| 108 | +* In GitHub, send a pull request to `itextpdf:develop`. |
| 109 | +* If we suggest changes then: |
| 110 | + * Make the required updates. |
| 111 | + * Re-run the iText test suite to ensure tests are still passing. |
| 112 | + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): |
| 113 | + |
| 114 | + ```shell |
| 115 | + git fetch origin |
| 116 | + git rebase develop -i |
| 117 | + git push my-remote my-fix-branch -f |
| 118 | + ``` |
| 119 | + |
| 120 | +That's it! Thank you for your contribution! |
| 121 | +
|
| 122 | +#### After your pull request is merged |
| 123 | +
|
| 124 | +After your pull request is merged, you can safely delete your branch and pull the changes |
| 125 | +from the main (upstream) repository: |
| 126 | +
|
| 127 | +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: |
| 128 | +
|
| 129 | + ```shell |
| 130 | + git push my-remote --delete my-fix-branch |
| 131 | + ``` |
| 132 | +
|
| 133 | +* Check out the develop branch: |
| 134 | +
|
| 135 | + ```shell |
| 136 | + git checkout develop -f |
| 137 | + ``` |
| 138 | +
|
| 139 | +* Delete the local branch: |
| 140 | +
|
| 141 | + ```shell |
| 142 | + git branch -D my-fix-branch |
| 143 | + ``` |
| 144 | +
|
| 145 | +* Update your develop with the latest upstream version: |
| 146 | +
|
| 147 | + ```shell |
| 148 | + git pull --ff upstream develop |
| 149 | + ``` |
| 150 | +
|
| 151 | +
|
| 152 | +## <a name="rules">Coding Rules</a> |
| 153 | +To ensure consistency throughout the source code, keep these rules in mind as you are working: |
| 154 | +
|
| 155 | +* All features or bug fixes **must be tested** by one or more [unit tests][unit-testing]. |
| 156 | +* All public API methods **must be documented** with JavaDoc. To see how we document our APIs, please check |
| 157 | + out the existing [javadocs][javadocs]. |
| 158 | +* We follow the rules contained in |
| 159 | + [Oracle's Code Conventions for the Java Programming Language][java-style-guide], with these additions: |
| 160 | + * Wrap all code at **100 characters**. |
| 161 | + |
| 162 | + |
| 163 | +## <a name="commit">Git Commit Guidelines</a> |
| 164 | + |
| 165 | +We have very precise rules over how our git commit messages can be formatted. This leads to **more |
| 166 | +readable messages** that are easy to follow when looking through the **project history**. But also, |
| 167 | +we use the git commit messages to **generate the iText change log**. |
| 168 | + |
| 169 | +### Commit Message Format |
| 170 | +Each commit message consists of a **subject**, a **body** and a **footer**: |
| 171 | + |
| 172 | +``` |
| 173 | +<subject> |
| 174 | +<BLANK LINE> |
| 175 | +<body> |
| 176 | +<BLANK LINE> |
| 177 | +<footer> |
| 178 | +``` |
| 179 | + |
| 180 | +Any line of the commit message cannot be longer 70 characters! This allows the message to be easier |
| 181 | +to read on GitHub as well as in various git tools. |
| 182 | + |
| 183 | +### Subject |
| 184 | +The subject contains succinct description of the change: |
| 185 | + |
| 186 | +* use the imperative, present tense: "change" not "changed" nor "changes" |
| 187 | +* don't capitalize first letter |
| 188 | +* no dot (.) at the end |
| 189 | +* describe what the **change** does, not the actions the developer has done |
| 190 | +
|
| 191 | +### Body |
| 192 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". |
| 193 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 194 | +
|
| 195 | +### Footer |
| 196 | +The footer should contain any information about **Breaking Changes** and is also the place to |
| 197 | +reference JIRA or GitHub issues that this commit **Closes**. |
| 198 | +
|
| 199 | +
|
| 200 | +## <a name="cla">Signing the iCLA</a> |
| 201 | +
|
| 202 | +Please sign the iText Contributor License Agreement (iCLA) before sending pull requests. For any larger code |
| 203 | +changes (more than 20 lines of significant code) to be accepted, the iCLA must be signed. It's a quick process, we promise! |
| 204 | + |
| 205 | +We'll need you to [(digitally) sign and then email, fax or mail the form][cla]. |
| 206 | +
|
| 207 | +
|
| 208 | +## <a name="coc">Contributor Code of Conduct</a> |
| 209 | +Please note that this project is released with a [Contributor Code of Conduct][coc]. By participating in this project you agree to abide by its terms. |
| 210 | +
|
| 211 | +We use the StackExchange network for free support and GitHub for code hosting. By using these services, you agree to abide by their terms: |
| 212 | +* StackExchange: http://stackexchange.com/legal |
| 213 | +* Github: https://help.github.com/articles/github-terms-of-service/ |
| 214 | +
|
| 215 | +
|
| 216 | +[cla]: http://itextpdf.com/policy |
| 217 | +[coc]: https://github.com/itext/itextpdf/blob/master/CODE_OF_CONDUCT.md |
| 218 | +[github]: https://github.com/itext/itextpdf |
| 219 | +[itext-dev]: https://lists.sourceforge.net/lists/listinfo/itext-developers |
| 220 | +[java-style-guide]: http://www.oracle.com/technetwork/java/codeconvtoc-136057.html |
| 221 | +[javadocs]: http://itextpdf.com/api |
| 222 | +[pull]: https://github.com/itext/itextpdf/pulls |
| 223 | +[sscce]: http://sscce.org/ |
| 224 | +[stackoverflow]: http://stackoverflow.com/questions/tagged/itext |
| 225 | +[good-questions]: http://stackoverflow.com/help/how-to-ask |
| 226 | +[mcve]: http://stackoverflow.com/help/mcve |
| 227 | +[support]: http://itextpdf.com/support |
| 228 | +[unit-testing]: http://junit.org/ |
0 commit comments