contributing.mkd 14.3 KB
Newer Older
1
2
3
# Contributing

Before you contribute you should read and understand the [license](license.mkd)
4
that _SquirrelJME_ is under. You should abide by the
5
6
7
[Code of Conduct](code-of-conduct.mkd), if you fail to keep the pledge your
contribution will not be accepted since it can create a toxic and unwelcoming
environment for developers and users.
8

9
 * For instructions on building, see [the building guide](building.mkd).
10
11
 * If you wish to maintain or become a maintainer please read the
   [developer guide](developer-guide.mkd)!
12

13
14
15
Development can happen on any operating system that has an installation of
Gradle, a Java JDK, any text editor/IDE (IntelliJ Ultimate is recommended), and
enough disk space to store the code and repository.
16

17
18
SquirrelJME uses the [Fossil](https://fossil-scm.org/) source control
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
21
22
however since the GitHub is a mirror of another repository it cannot be
directly committed to as those commits will be erased, however Pull Requests
can still be made. Continue reading below for a contributing guide.
23

24
25
26
27
28
29
30
31
32
33
34
35
## Etiquette For Contributing

As with various other projects that exist, please be considerate of how
_SquirrelJME_ is structured along with maintaining consistency within the
repository as a whole.

 * Follow the existing syntax and code style of the project.
   * Keep the syntax the same for consistency, changes to the syntax will
     cause breakage and result in difficult to merge patches especially so
     when there are different and various branches. There would also be many
     unrelated changes which changes the purpose of a patch.
   * Do not mass reformat files and be careful of IDEs automatically
36
     reformatting/refactoring files.
37
38
39
   * If there are linters or code style formatters that are not configured
     for the project for _SquirrelJME_'s code style, configure them for
     _SquirrelJME_ and add them to the repository.
40
41
42
43
44
 * Make sure your code is well documented and has the JavaDoc for the
   library functions.
   * _Do not_ copy and paste from other Java libraries, it is not legal to do
     so. You must express what the method, class, or otherwise does in your
     own words.
45
46
47
 * Ensure that the tests pass.
   * Note that submissions on GitHub will automatically be run under CI/CD
     and if there are any issues arising from this, they must be addressed.
48
   * You can run all of the tests with the `gradlew testHosted` command.
49
50
51
52
 * Do not perform mass automatic refactorings.
   * These mass refactorings can cause unintended side effects and as well
     may cause breakages. Also as well, these can cause merge conflicts and
     otherwise.
53
54
 * The `trunk` branch is _always_ stable code. It must _always_ pass and
   be in a state of release!
55
56
57
58
59
 * Do not copy and paste code from _Stack Overflow_ or other Java projects
   such as but not limited to OpenJDK, PhoneME, Apache Harmony, GNU GCJ/GIJ,
   GNU ClassPath, Android, OpenJ9, and others.
 * Do not copy and paste JavaDoc or other documentation from other Java
   projects. Documentation is copy written by the original writers. 
60
61
62
63
64

If there are any issues regarding these, please open an issue describing in
detail the problem and a proposed solution if there is one on [GitHub](
https://github.com/SquirrelJME/SquirrelJME/issues).

65
66
## Exceptions to Contributing

Stephanie Gawroriski's avatar
Stephanie Gawroriski committed
67
68
If you have worked on the following projects for the following companies, you
are not permitted to contribute to this project due to potential poisoning:
69
70
71
72
73
74
75

 * _Apache_:
   * Apache Harmony
 * _Free Software Foundation_:
   * GNU Compiler for Java (GCJ)
   * GNU Classpath
   * GNU Interpreter for Java (GIJ)
Stephanie Gawroriski's avatar
Stephanie Gawroriski committed
76
77
 * _Google_:
   * Android
78
79
80
81
82
83
84
85
86
87
 * _IBM_:
   * _OpenJ9_
 * _Microsoft_:
   * Microsoft Java Virtual Machine (MSJVM)
 * _Oracle_/_Sun Microsystems_:
   * HotSpot
   * Java (eventually became OpenJDK)
   * OpenJDK
   * PhoneME

88
## Contributor Agreement
89

90
**ALL CONTRIBUTORS MUST ACCEPT THE FOLLOWING AGREEMENT BEFORE THEIR CODE WILL**
91
92
93
94
**BE ACCEPTED IN THE PROJECT. IF THE DEVELOPER IS EMPLOYED AND DEVELOPS THE**
**CODE "ON THE CLOCK" OR UNDER CONTRACT, THEN THAT DEVELOPER MUST SEEK THE**
**PERMISSION OF THE EMPLOYER.**

Stephanie Gawroriski's avatar
Stephanie Gawroriski committed
95
	You grant Stephanie Gawroriski an irrevocable license that:
96
    
97
98
	 1. That you own the contributing work.
	 2. Grants a patent license, as per the GNU GPLv3.
Stephanie Gawroriski's avatar
Stephanie Gawroriski committed
99
100
101
102
103
	 3. Granting Stephanie Gawroriski permission to redistribute, sell, lease,
	    modify, transform, translate, and relicense the specified works. This
	    is to simplify the licensing of the project and permit it to be
	    consistent. Your contribution may be commercially licensed to other
	    parties supporting the project through this means.
104
	 4. If employed by a company, you have a right by that company to provide
105
	    contributions to this project.
106
	 5. Have pledged to follow the Code of Conduct.
107
	 6. Have read and understand the Ettiquite.
108
109
110
111
112
113
114
115
116
117
118
119
120

## Committing and Submitting Changes

As previously stated, _SquirrelJME_ is developed using
[Fossil](https://fossil-scm.org/) but if you are not comfortable with it and
would like to stick to something more familiar then you may also as well use
[Git](https://git-scm.com/).

For reference, the two sections will accordingly be:

 * With Fossil
 * With Git

121
122
123
All development should be done in branches so that way `trunk` on your own
copy of the repository is always aligned to `trunk` on the remote repository.

124
125
### With Fossil

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
_SquirrelJME_ uses [Fossil](https://fossil-scm.org/) which is a distributed
version control system that keeps the entire repository within a single file
along with having support for other features such as web hosting and
otherwise. It is slightly different from Git but it is simple to use and
works on Windows, Linux, and Mac OS X.

 * On Windows, you may...:
   * Extract the ZIP archive to your `%PATH%`.
     * This is somewhere such as `C:\Windows\System32`.
     * Alternatively it can be placed elsewhere if you refer to it via the
       absolute path or _edit the system environment variables_ (this can be
       searched for in Windows 10).
 * On Linux, you may...:
   * Extract the TAR archive to your `$PATH`.
   * Install with a package manager:
     * `apt-get install fossil`
     * `pacman -S fossil`
 * On Mac OS X, you may...:
   * Extract the TAR archive to your `$PATH`.
   * Install via Brew: `brew install fossil`
     * More info [here](https://formulae.brew.sh/formula/fossil).

After fossil is installed, the repository can be checked out as follows (do
make sure that `yourname` does not contain any spaces and is all lowercase,
it may contain dots, an example being: `jane.doe`):

 * Clone the repository to your computer:
   * `fossil clone -u -A yourname https://squirreljme.cc/ squirreljme.fossil`
 * Create a directory where the checkout will go:
   * `mkdir squirreljme`
 * Navigate to the directory where development will occur:
   * `cd squirreljme`
 * Open the repository, this will load all the contents into this directory:
   * `fossil open ../squirreljme.fossil`

161
162
163
164
165
166
167
168
It is preferred that your commits are signed using a PGP/GPG key, to enable
this do the following:

 * To enable commit signing:
   * `fossil settings clearsign on`
 * If there is difficulty finding the PGP command, there is this setting:
   * `fossil settings pgp-command theCorrectPGPCommand`

169
170
After this you are ready to start development!

171
172
173
For reference, there are some guides for Fossil:

 * [Fossil quick-start guide](
174
https://www.fossil-scm.org/xfer/doc/tip/www/quickstart.wiki).
175
176
 * [Fossil hints for users of Git](
https://www.fossil-scm.org/xfer/doc/trunk/www/gitusers.md).
177
178
179
180
181
182
183

#### Starting A Branch

Development should be done in branches and not the main `trunk` as there will
be a number of changes and will require constant updates:

 * Create a new branch, based off `trunk`:
184
   * `fossil branch new wip-branch trunk`
185
 * Switching to that branch:
186
187
188
   * `fossil update wip-branch`

Please start your branch with `wip-` when making a branch!
189

190
#### Committing and Making Changes
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214

When you are ready to commit your changes to your branch, you may do the
following:

 * Making a commit:
   * `fossil commit`
   * Enter the commit description accordingly.

#### Staying Up To Date

Since SquirrelJME is actively worked on, there will be changes to other
branches and the main `trunk` line. You can use the following commands for
this:

 * Synchronizing your repository with the main repository:
   * `fossil sync -u`
 * Updating your currently checked out branch to the latest code in that
   version:
   * `fossil update`
 * _If you are on your own branch_ and you want to update your branch to
   the code that is latest within `trunk`:
   * Make sure you commit any of your current changes or they will be lost:
     * `fossil commit`
   * Update to the branch to be updated:
215
     * `fossil update wip-branch`
216
217
218
219
220
221
222
223
224
225
226
227
   * Merge in the changes that were made in `trunk`:
     * `fossil merge trunk`
   * Commit the merge:
     * `fossil commit`

#### Submitting

When you are ready to submit please note that your submission will be reviewed
and may or may not be accepted. There may be additional requests for changes
as well. To make a submission do the following:

 * Create a bundle for your branch:
228
   * `fossil bundle export wip-branch.bun --branch wip-branch --standalone`
229
230
231
232
233
234
235
236
237
238
 * Send a copy of this bundle via E-Mail or another means:
   * Via e-mail:
     * Mail to <xer@multiphasicapps.net> OR <xerthesquirrel@gmail.com>.
     * _In the SUBJECT line, include:_ "SquirrelJME Patch Submission"
     * _In the MESSAGE BODY_, place that you _agree_ to the contributor
       agreement as noted above in this document.
   * Via the _SquirrelJME_ Discord:
     * Mention `@XerTheSquirrel#5366`, with an upload of the bundle (it may
       be in a ZIP file) and that you _agree_ to the contributor
       agreement as noted above in this document.
239
240
241
242
243
     * Note that Discord has a file size limit, if your file is too big please
       e-mail it or use a file sharing service. Do note that if you use a
       file sharing service ensure that it has a long expiration (at least
       30 days) otherwise due to the busy schedules of the developers your
       contribution may be lost.
244
245
246

### With Git

247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
Although _SquirrelJME_ does not use [Git](https://git-scm.com/) there are
mirrors to both [GitHub](https://github.com/SquirrelJME/SquirrelJME) and
[GitLab](https://gitlab.com/xerthesquirrel/SquirrelJME). Do note that the
primary mirror is on _GitHub_. Note that if you are using _GitHub_ or _GitLab_
you should fork the repository.

 * Links to forking guides:
   * [GitHub](https://guides.github.com/activities/forking/)
   * [GitLab](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html)

Once you have a fork you may check it out:

 * Via the Command Line
   * Clone the repository:
     * `git clone yourForkUrl squirreljme`
   * Navigate to the repository:
     * `cd squirreljme`
 * Using an IDE:
   * IntelliJ Community and IntelliJ Ultimate:
     * Navigate to _File_ > _New_ > _Project from Version Control_.
     * Use the _Project URL_ for _your fork_.
     * Select the _Clone_ button or press _Enter_.

270
271
272
It is preferred that your commits are signed using a PGP/GPG key, to enable
this do the following:

Stephanie Gawroriski's avatar
Update.    
Stephanie Gawroriski committed
273
 * Please read the following guides:
274
275
276
277
   * <https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work>
   * <https://help.github.com/en/github/authenticating-to-github/signing-commits>
   * <https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/>

278
279
280
281
282
283
284
285
After this you are ready to start development!

#### Starting A Branch

Development should be done in branches and not the main `trunk` as there will
be a number of changes and will require constant updates:

  * Checkout a new branch:
286
287
288
    * `git checkout -b wip-branch`

Please start your branch with `wip-` when making a branch!
289
290
291
292
293
294

#### Committing and Making Changes

When you are ready to commit your changes to your branch, you may do the
following:

295
296
297
298
 * Adding files and changes to be committed:
   * `git add nameOfFile`
   * Please _do not_ use `git add .` as it will add every un-related file
     to the commit and repository!
299
300
301
302
303
304
305
 * Making a commit:
   * `git commit`
   * Enter the commit description accordingly.
 * Pushing your changes to a remote repository (if applicable):
   * `git push`
   * Note that you may have to set the upstream for the branch, the push
     command should tell you how to do this but for reference it is:
306
     * `git push --set-upstream origin wip-branch`
307
308
309
310
311
312
313

#### Staying Up To Date

Since SquirrelJME is actively worked on, there will be changes to other
branches and the main `trunk` line. You can use the following commands for
this:

314
315
316
317
318
 * Checkout the `trunk` branch:
   * `git checkout trunk`
 * Pull in the latest changes:
   * `git pull`
 * Checkout your branch:
319
   * `git checkout wip-branch`
320
321
322
323
324
 * Merge in the changes from `trunk`:
   * `git merge trunk`
 * Git should automatically commit, if there are conflicts are a merge commit
   was not made then, you may:
   * `git commit`
325
326
327
328
329
330
331
332
333
334
335
336
337
338

#### Submitting

When you are ready to submit please note that your submission will be reviewed
and may or may not be accepted. There may be additional requests for changes
as well. To make a submission do the following:

 * Via [GitHub](https://guides.github.com/activities/forking/):
   * Create a _Pull Request_.
 * Via [GitLab](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html):
   * Create a _Merge Request_.

Alternatively a Git Bundle may be used:

339
 * Create a patch bundle for your branch:
340
   * `git format-patch --binary --stdout --attach -n trunk..wip-branch > wip-branch.bun`
341
 * Send a copy of this patch bundle via E-Mail or another means:
342
343
344
345
346
347
348
349
350
   * Via e-mail:
     * Mail to <xer@multiphasicapps.net> OR <xerthesquirrel@gmail.com>.
     * _In the SUBJECT line, include:_ "SquirrelJME Patch Submission"
     * _In the MESSAGE BODY_, place that you _agree_ to the contributor
       agreement as noted above in this document.
   * Via the _SquirrelJME_ Discord:
     * Mention `@XerTheSquirrel#5366`, with an upload of the bundle (it may
       be in a ZIP file) and that you _agree_ to the contributor
       agreement as noted above in this document.
351
352
353
354
355
     * Note that Discord has a file size limit, if your file is too big please
       e-mail it or use a file sharing service. Do note that if you use a
       file sharing service ensure that it has a long expiration (at least
       30 days) otherwise due to the busy schedules of the developers your
       contribution may be lost.