| blob | cb01cf5a6b1c8d75879f74d365b68734d94157dc |
1 # Contributing
3 Before you contribute you should read and understand the [license](license.mkd)
4 that _SquirrelJME_ is under. You should abide by the
5 [Code of Conduct](code-of-conduct.mkd), if you fail to keep the pledge your
6 contribution will not be accepted since it can create a toxic and unwelcoming
7 environment for developers and users.
9 * For instructions on building, see [the building guide](building.mkd).
10 * If you wish to maintain or become a maintainer please read the
11 [developer guide](developer-guide.mkd)!
13 Development can happen on any operating system that has an installation of
14 Gradle, a Java JDK, any text editor/IDE (IntelliJ Ultimate is recommended), and
15 enough disk space to store the code and repository.
17 SquirrelJME uses the [Fossil](https://fossil-scm.org/) source control
18 system and as such it generally is expected that it is to be used. There also
19 are [GitHub Pull Requests](https://github.com/SquirrelJME/SquirrelJME/pulls)
20 however since the GitHub is a mirror of another repository it cannot be
21 directly committed to as those commits will be erased, however Pull Requests
22 can still be made. Any pull requests made on GitHub will be converted to
23 Fossil then merged in accordingly.
25 Continue reading below for the contributing guide.
27 ## Etiquette For Contributing
29 As with various other projects that exist, please be considerate of how
30 _SquirrelJME_ is structured along with maintaining consistency within the
31 repository as a whole.
33 * Follow the existing syntax and code style of the project.
34 * Keep the syntax the same for consistency, changes to the syntax will
35 cause breakage and result in difficult to merge patches especially so
36 when there are different and various branches. There would also be many
37 unrelated changes which changes the purpose of a patch.
38 * Do not mass reformat files and be careful of IDEs automatically
39 reformatting/refactoring files.
40 * If there are linters or code style formatters that are not configured
41 for the project for _SquirrelJME_'s code style, configure them for
42 _SquirrelJME_ and add them to the repository.
43 * If any code is incomplete, for any execution path that leads to incomplete
44 code then `Debugging.todo()` must be used so that such incomplete code is
45 fail-fast and prevents continued operation.
46 * New code must have tests implemented, following the guide in the
47 [Test Writing](test-writing.mkd) document.
48 * Make sure your code is well documented and has the JavaDoc for the
49 library functions.
50 * _Do not_ copy and paste from other Java libraries, it is not legal to do
51 so. You must express what the method, class, or otherwise does in your
52 own words.
53 * Ensure that the tests pass.
54 * Note that submissions on GitHub will automatically be run under CI/CD
55 and if there are any issues arising from this, they must be addressed.
56 * You can run all the tests with the `gradlew testHosted` and
57 `gradlew testSpringCoat` command.
58 * Do not perform mass automatic refactorings.
59 * These mass refactorings can cause unintended side effects and as well
60 may cause breakages. Also as well, these can cause merge conflicts and
61 otherwise.
62 * The `trunk` branch is _always_ stable code. It must _always_ pass and
63 be in a state of release!
64 * Do not copy and paste code from _Stack Overflow_ or other Java projects
65 such as but not limited to OpenJDK, PhoneME, Apache Harmony, GNU GCJ/GIJ,
66 GNU ClassPath, Android, OpenJ9, and others.
67 * Do not copy and paste JavaDoc or other documentation from other Java
68 projects. Documentation is copy written by the original writers.
70 If there are any issues regarding these, please open an issue describing in
71 detail the problem and a proposed solution if there is one on [GitHub](
72 https://github.com/SquirrelJME/SquirrelJME/issues).
74 ## Exceptions to Contributing
76 If you have worked on the following projects for the following companies, you
77 are not permitted to contribute to this project due to potential poisoning:
79 * _Apache_:
80 * Apache Harmony
81 * _Free Software Foundation_:
82 * GNU Compiler for Java (GCJ)
83 * GNU Classpath
84 * GNU Interpreter for Java (GIJ)
85 * _Google_:
86 * Android
87 * _IBM_:
88 * _OpenJ9_
89 * _Microsoft_:
90 * Microsoft Java Virtual Machine (MSJVM)
91 * _Oracle_/_Sun Microsystems_:
92 * HotSpot
93 * Java (eventually became OpenJDK)
94 * OpenJDK and any of its variants
95 * PhoneME
97 Additionally, for legal purposes, code that is derived from the source code
98 from these projects cannot be used.
100 ## Contributor Agreement
102 **ALL CONTRIBUTORS MUST ACCEPT THE FOLLOWING AGREEMENT BEFORE THEIR CODE WILL**
103 **BE ACCEPTED IN THE PROJECT. IF THE DEVELOPER IS EMPLOYED AND DEVELOPS THE**
104 **CODE "ON THE CLOCK" OR UNDER CONTRACT, THEN THAT DEVELOPER MUST SEEK THE**
105 **PERMISSION OF THE EMPLOYER.**
107 You grant Stephanie Gawroriski an irrevocable license that:
109 1. That you own the contributing work.
110 2. Grants a patent license, as per the GNU GPLv3.
111 3. Granting Stephanie Gawroriski permission to redistribute, sell, lease,
112 modify, transform, translate, and relicense the specified works. This
113 is to simplify the licensing of the project and permit it to be
114 consistent. Your contribution may be commercially licensed to other
115 parties supporting the project through this means.
116 4. If employed by a company, you have a right by that company to provide
117 contributions to this project.
118 5. Have pledged to follow the Code of Conduct.
119 6. Have read and understand the Ettiquite.
121 ## Committing and Submitting Changes
123 As previously stated, _SquirrelJME_ is developed using
124 [Fossil](https://fossil-scm.org/) but if you are not comfortable with it and
125 would like to stick to something more familiar then you may also as well use
126 [Git](https://git-scm.com/).
128 For reference, the two sections will accordingly be:
130 * With Fossil
131 * With Git
133 All development should be done in branches so that way `trunk` on your own
134 copy of the repository is always aligned to `trunk` on the remote repository.
136 ### With Fossil
138 _SquirrelJME_ uses [Fossil](https://fossil-scm.org/) which is a distributed
139 version control system that keeps the entire repository within a single file
140 along with having support for other features such as web hosting and
141 otherwise. It is slightly different from Git but it is simple to use and
142 works on Windows, Linux, and Mac OS X.
144 * On Windows, you may...:
145 * Extract the ZIP archive to your `%PATH%`.
146 * This is somewhere such as `C:\Windows\System32`.
147 * Alternatively it can be placed elsewhere if you refer to it via the
148 absolute path or _edit the system environment variables_ (this can be
149 searched for in Windows 10).
150 * On Linux, you may...:
151 * Extract the TAR archive to your `$PATH`.
152 * Install with a package manager:
153 * `apt-get install fossil`
154 * `pacman -S fossil`
155 * On Mac OS X, you may...:
156 * Extract the TAR archive to your `$PATH`.
157 * Install via Brew: `brew install fossil`
158 * More info [here](https://formulae.brew.sh/formula/fossil).
160 After fossil is installed, the repository can be checked out as follows (do
161 make sure that `yourname` does not contain any spaces and is all lowercase,
162 it may contain dots, an example being: `jane.doe`):
164 * Clone the repository to your computer:
165 * `fossil clone -u -A yourname https://squirreljme.cc/ squirreljme.fossil`
166 * Create a directory where the checkout will go:
167 * `mkdir squirreljme`
168 * Navigate to the directory where development will occur:
169 * `cd squirreljme`
170 * Open the repository, this will load all the contents into this directory:
171 * `fossil open ../squirreljme.fossil`
173 It is preferred that your commits are signed using a PGP/GPG key, to enable
174 this do the following:
176 * To enable commit signing:
177 * `fossil settings clearsign on`
178 * If there is difficulty finding the PGP command, there is this setting:
179 * `fossil settings pgp-command theCorrectPGPCommand`
181 After this you are ready to start development!
183 For reference, there are some guides for Fossil:
185 * [Fossil quick-start guide](
186 https://www.fossil-scm.org/xfer/doc/tip/www/quickstart.wiki).
187 * [Fossil hints for users of Git](
188 https://www.fossil-scm.org/xfer/doc/trunk/www/gitusers.md).
190 #### Starting A Branch
192 Development should be done in branches and not the main `trunk` as there will
193 be a number of changes and will require constant updates:
195 * Create a new branch, based off `trunk`:
196 * `fossil branch new wip-branch trunk`
197 * Switching to that branch:
198 * `fossil update wip-branch`
200 Please start your branch with `wip-` when making a branch!
202 #### Committing and Making Changes
204 When you are ready to commit your changes to your branch, you may do the
205 following:
207 * Making a commit:
208 * `fossil commit`
209 * Enter the commit description accordingly.
211 #### Staying Up To Date
213 Since SquirrelJME is actively worked on, there will be changes to other
214 branches and the main `trunk` line. You can use the following commands for
215 this:
217 * Synchronizing your repository with the main repository:
218 * `fossil sync -u`
219 * Updating your currently checked out branch to the latest code in that
220 version:
221 * `fossil update`
222 * _If you are on your own branch_ and you want to update your branch to
223 the code that is latest within `trunk`:
224 * Make sure you commit any of your current changes or they will be lost:
225 * `fossil commit`
226 * Update to the branch to be updated:
227 * `fossil update wip-branch`
228 * Merge in the changes that were made in `trunk`:
229 * `fossil merge trunk`
230 * Commit the merge:
231 * `fossil commit`
233 #### Submitting
235 When you are ready to submit please note that your submission will be reviewed
236 and may or may not be accepted. There may be additional requests for changes
237 as well. To make a submission do the following:
239 * Create a bundle for your branch:
240 * `fossil bundle export wip-branch.bun --branch wip-branch --standalone`
241 * Send a copy of this bundle via E-Mail or another means:
242 * Via e-mail:
243 * Mail to <xer@multiphasicapps.net> OR <xerthesquirrel@gmail.com>.
244 * _In the SUBJECT line, include:_ "SquirrelJME Patch Submission"
245 * _In the MESSAGE BODY_, place that you _agree_ to the contributor
246 agreement as noted above in this document.
247 * Via the _SquirrelJME_ Discord:
248 * Mention `@XerTheSquirrel#5366`, with an upload of the bundle (it may
249 be in a ZIP file) and that you _agree_ to the contributor
250 agreement as noted above in this document.
251 * Note that Discord has a file size limit, if your file is too big please
252 e-mail it or use a file sharing service. Do note that if you use a
253 file sharing service ensure that it has a long expiration (at least
254 30 days) otherwise due to the busy schedules of the developers your
255 contribution may be lost.
257 ### With Git
259 Although _SquirrelJME_ does not use [Git](https://git-scm.com/) there are
260 mirrors to both [GitHub](https://github.com/SquirrelJME/SquirrelJME) and
261 [GitLab](https://gitlab.com/xerthesquirrel/SquirrelJME). Do note that the
262 primary mirror is on _GitHub_. Note that if you are using _GitHub_ or _GitLab_
263 you should fork the repository.
265 * Links to forking guides:
266 * [GitHub](https://guides.github.com/activities/forking/)
267 * [GitLab](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html)
269 Once you have a fork you may check it out:
271 * Via the Command Line
272 * Clone the repository:
273 * `git clone yourForkUrl squirreljme`
274 * Navigate to the repository:
275 * `cd squirreljme`
276 * Using an IDE:
277 * IntelliJ Community and IntelliJ Ultimate:
278 * Navigate to _File_ > _New_ > _Project from Version Control_.
279 * Use the _Project URL_ for _your fork_.
280 * Select the _Clone_ button or press _Enter_.
282 It is preferred that your commits are signed using a PGP/GPG key, to enable
283 this do the following:
285 * Please read the following guides:
286 * <https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work>
287 * <https://help.github.com/en/github/authenticating-to-github/signing-commits>
288 * <https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/>
290 After this you are ready to start development!
292 #### Starting A Branch
294 Development should be done in branches and not the main `trunk` as there will
295 be a number of changes and will require constant updates:
297 * Checkout a new branch:
298 * `git checkout -b wip-branch`
300 Please start your branch with `wip-` when making a branch!
302 #### Committing and Making Changes
304 When you are ready to commit your changes to your branch, you may do the
305 following:
307 * Adding files and changes to be committed:
308 * `git add nameOfFile`
309 * Please _do not_ use `git add .` as it will add every un-related file
310 to the commit and repository!
311 * Making a commit:
312 * `git commit`
313 * Enter the commit description accordingly.
314 * Pushing your changes to a remote repository (if applicable):
315 * `git push`
316 * Note that you may have to set the upstream for the branch, the push
317 command should tell you how to do this but for reference it is:
318 * `git push --set-upstream origin wip-branch`
320 #### Staying Up To Date
322 Since SquirrelJME is actively worked on, there will be changes to other
323 branches and the main `trunk` line. You can use the following commands for
324 this:
326 * Checkout the `trunk` branch:
327 * `git checkout trunk`
328 * Pull in the latest changes:
329 * `git pull`
330 * Checkout your branch:
331 * `git checkout wip-branch`
332 * Merge in the changes from `trunk`:
333 * `git merge trunk`
334 * Git should automatically commit, if there are conflicts are a merge commit
335 was not made then, you may:
336 * `git commit`
338 #### Submitting
340 When you are ready to submit please note that your submission will be reviewed
341 and may or may not be accepted. There may be additional requests for changes
342 as well. To make a submission do the following:
344 * Via [GitHub](https://guides.github.com/activities/forking/):
345 * Create a _Pull Request_.
346 * Via [GitLab](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html):
347 * Create a _Merge Request_.
349 Alternatively a Git Bundle may be used:
351 * Create a patch bundle for your branch:
352 * `git format-patch --binary --stdout --attach -n trunk..wip-branch > wip-branch.bun`
353 * Send a copy of this patch bundle via E-Mail or another means:
354 * Via e-mail:
355 * Mail to <xer@multiphasicapps.net> OR <xerthesquirrel@gmail.com>.
356 * _In the SUBJECT line, include:_ "SquirrelJME Patch Submission"
357 * _In the MESSAGE BODY_, place that you _agree_ to the contributor
358 agreement as noted above in this document.
359 * Via the _SquirrelJME_ Discord:
360 * Mention `@XerTheSquirrel#5366`, with an upload of the bundle (it may
361 be in a ZIP file) and that you _agree_ to the contributor
362 agreement as noted above in this document.
363 * Note that Discord has a file size limit, if your file is too big please
364 e-mail it or use a file sharing service. Do note that if you use a
365 file sharing service ensure that it has a long expiration (at least
366 30 days) otherwise due to the busy schedules of the developers your
367 contribution may be lost.