|
| 1 | +# Contributing to Apache Tomcat |
| 2 | + |
| 3 | +Firstly, thanks for your interest in contributing! I hope that this will be a |
| 4 | +pleasant experience for you, and that you will return to continue |
| 5 | +contributing. |
| 6 | + |
| 7 | +Please visit our [Get Involved page](https://tomcat.apache.org/getinvolved.html) |
| 8 | +for more information on how to contribute. |
| 9 | + |
| 10 | +## Code of Conduct |
| 11 | + |
| 12 | +This project and everyone participating in it are governed by the Apache |
| 13 | +software Foundation's |
| 14 | +[Code of Conduct](https://www.apache.org/foundation/policies/conduct.html). By |
| 15 | +participating, you are expected to adhere to this code. If you are aware of |
| 16 | +unacceptable behavior, please visit the |
| 17 | +[Reporting Guidelines page](https://www.apache.org/foundation/policies/conduct.html#reporting-guidelines) |
| 18 | +and follow the instructions there. |
| 19 | + |
| 20 | +## How Can I Contribute? |
| 21 | + |
| 22 | +Most of the contributions that we receive are code contributions, but you can |
| 23 | +also contribute to the documentation, wiki, etc., or simply report solid bugs |
| 24 | +for us to fix. |
| 25 | + |
| 26 | +### Reporting Bugs |
| 27 | + |
| 28 | +Please review our [guide](https://tomcat.apache.org/bugreport.html) on how to |
| 29 | +submit a bug report. This page also has links to other resources to assist |
| 30 | +you. |
| 31 | + |
| 32 | +### Reporting Translation improvements |
| 33 | + |
| 34 | +Apache Tomcat project uses POEditor for managing the localization files. |
| 35 | +Please see more at https://cwiki.apache.org/confluence/x/vIPzBQ |
| 36 | + |
| 37 | +### Your First Code Contribution |
| 38 | + |
| 39 | +### Trouble Deciding How to Contribute? |
| 40 | + |
| 41 | +Unsure where to begin contributing to Tomcat? You can start by taking a look at |
| 42 | +the issues marked 'Beginner', link below. Please note that the Beginner keyword |
| 43 | +is pretty new to the project, so if there aren't any issues in the filter feel |
| 44 | +free to ask on the [dev list](https://tomcat.apache.org/lists.html#tomcat-dev). |
| 45 | + |
| 46 | +* [Beginner issues](https://bz.apache.org/bugzilla/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=NEEDINFO&keywords=Beginner&keywords_type=allwords&list_id=160824&product=Tomcat%207&product=Tomcat%208.5&product=Tomcat%209&query_format=advanced) - |
| 47 | +issues which should only require a few lines of code, and a test or two to |
| 48 | +resolve. |
| 49 | + |
| 50 | +The list above shows all bugs that are marked 'Beginner' and are open in the |
| 51 | +currently supported Tomcat versions (7, 8.5, and 9). |
| 52 | + |
| 53 | +If you prefer C over Java, you may also take a look at the tomcat-native and |
| 54 | +Tomcat Connectors products in Bugzilla. |
| 55 | + |
| 56 | +### How to Provide Your First Patch |
| 57 | + |
| 58 | +Excited yet? This section will guide you through providing a patch to the |
| 59 | +committers of the project for review and acceptance. |
| 60 | + |
| 61 | +##### Choose Your Method of Submission |
| 62 | + |
| 63 | +You can provide a patch in one of the following ways (in order of preference): |
| 64 | + |
| 65 | +* GitHub Pull Request |
| 66 | +* Patch attachment to the Bugzilla issue |
| 67 | +* Email the patch to the developer list. This is not preferred, but if no bug |
| 68 | +is associated with the patch, or you would like a developer review, an email |
| 69 | +may be appropriate. |
| 70 | + |
| 71 | +##### Get the Sources |
| 72 | + |
| 73 | +Now that you've chosen how you want to submit a patch, you need to get the |
| 74 | +source code. |
| 75 | + |
| 76 | +###### Download The Source Distribution |
| 77 | + |
| 78 | +This method works if you want to submit a patch via email, but |
| 79 | +the difference in using the sources distribution and a VCS is that you have to |
| 80 | +manually generate the patch file by using diff. If this is what you want, you |
| 81 | +can download the sources from the "Source Code Distributions" section of the |
| 82 | +Download Page. There is one such page for every major Tomcat version: |
| 83 | + |
| 84 | +- [Tomcat 10](https://tomcat.apache.org/download-10.cgi) |
| 85 | +- [Tomcat 9](https://tomcat.apache.org/download-90.cgi) |
| 86 | +- [Tomcat 8](https://tomcat.apache.org/download-80.cgi) |
| 87 | +- [Tomcat 7](https://tomcat.apache.org/download-70.cgi) |
| 88 | + |
| 89 | +##### Manual Patch Generation |
| 90 | + |
| 91 | +If you have chosen to attach a patch to the Bugzilla issue (or email |
| 92 | +one), then you'll need to download the sources as noted above, make your |
| 93 | +desired changes and then manually generate your patch using diff (or any |
| 94 | +other tool). |
| 95 | + |
| 96 | +##### GitHub |
| 97 | + |
| 98 | +To submit a GitHub Pull Request you'll need to fork the |
| 99 | +[repository](https://github.com/apache/tomcat), clone your fork to do the work: |
| 100 | + |
| 101 | +``` |
| 102 | +$ git clone https://github.com/$USERNAME/tomcat.git |
| 103 | +``` |
| 104 | + |
| 105 | +and then push your changes, and submit a Pull Request via the GitHub UI. |
| 106 | + |
| 107 | +#### Submitting Your Patch! |
| 108 | + |
| 109 | +After you've chosen your method of submission, retrieved the sources, and |
| 110 | +fixed the issue it's time to submit your work. At this point, just follow |
| 111 | +the method of submission you chose earlier. |
| 112 | + |
| 113 | +* GitHub PR - after resolving the issue in your local fork and pushing to your |
| 114 | +copy of the repository, open a GitHub PR for review. |
| 115 | +* Bugzilla attachment - attach the patch to the Bugzilla issue |
| 116 | +* Email - again, not preferred, but you may send an email to the developer list |
| 117 | +with a patch attached for review. |
| 118 | + |
| 119 | +#### Waiting For Feedback |
| 120 | + |
| 121 | +It may take a while for committers to review. Please be patient during this |
| 122 | +time as all committers are volunteers on the project. If a significant amount |
| 123 | +of time has lapsed since your submission, such as a couple of months, feel free |
| 124 | +to either update your BZ, PR, or email the dev list with a message to bump your |
| 125 | +issue. Sometimes things get lost in all the work and we need a reminder :smile: |
| 126 | + |
| 127 | +## IDE Support |
| 128 | + |
| 129 | +Special IDE support for |
| 130 | +[Eclipse](https://www.eclipse.org/ide/), |
| 131 | +[IntelliJ IDEA](https://www.jetbrains.com/idea/) and |
| 132 | +[NetBeans](https://netbeans.org/) |
| 133 | +is provided through special ant targets: |
| 134 | + |
| 135 | +```bash |
| 136 | +ant ide-eclipse |
| 137 | +``` |
| 138 | +```bash |
| 139 | +ant ide-intellij |
| 140 | +``` |
| 141 | +```bash |
| 142 | +ant ide-netbeans |
| 143 | +``` |
| 144 | + |
| 145 | +Just execute the ant target for your IDE after checking out the sources |
| 146 | +to set up the appropriate configuration files. |
| 147 | +Also make sure to re-execute the target after switching branches or |
| 148 | +after pulling upstream changes in order to keep your IDE configurations in sync. |
| 149 | + |
| 150 | +## Style Guide |
| 151 | + |
| 152 | +Apache Tomcat has very loosely defined coding conventions, but the following |
| 153 | +guidelines will be useful: |
| 154 | + |
| 155 | +* Use spaces for indenting, not tabs |
| 156 | +* 100 char line width for Java source, 80 char line width for documentation |
| 157 | +source (.txt, .xml) |
| 158 | +* Java source: { at end of line, 4 space indents |
| 159 | +* XML source: 2 space indents |
| 160 | + |
| 161 | +## Did we miss something? |
| 162 | + |
| 163 | +Have you reviewed this guide and found it lacking? Or are you confused about |
| 164 | +some particular step? If so, please let us know! Or better yet, submit a PR to |
| 165 | +address the issue :wink: |
0 commit comments