contributing.mkd

   1 # Contributing
   2
   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.
   8
   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)!
  12
  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.
  16
  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.
  24
  25 Continue reading below for the contributing guide.
  26
  27 ## Etiquette For Contributing
  28
  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.
  32
  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.
  69
  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).
  73
  74 ## Exceptions to Contributing
  75
  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:
  78
  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
  96
  97 Additionally, for legal purposes, code that is derived from the source code
  98 from these projects cannot be used.
  99
 100 ## Contributor Agreement
 101
 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.**
 106
 107         You grant Stephanie Gawroriski an irrevocable license that:
 108
 109          1. That you own the contributing work.
 110          2. Grants a patent license, as per the Mozilla Public License 2.0.
 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.
 120
 121 ## Committing and Submitting Changes
 122
 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/).
 127
 128 For reference, the two sections will accordingly be:
 129
 130  * With Fossil
 131  * With Git
 132
 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.
 135
 136 ### With Fossil
 137
 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.
 143
 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).
 159
 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`):
 163
 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`
 172
 173 It is preferred that your commits are signed using a PGP/GPG key, to enable
 174 this do the following:
 175
 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`
 180
 181 After this you are ready to start development!
 182
 183 For reference, there are some guides for Fossil:
 184
 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).
 189
 190 #### Starting A Branch
 191
 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:
 194
 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`
 199
 200 Please start your branch with `wip-` when making a branch!
 201
 202 #### Committing and Making Changes
 203
 204 When you are ready to commit your changes to your branch, you may do the
 205 following:
 206
 207  * Making a commit:
 208    * `fossil commit`
 209    * Enter the commit description accordingly.
 210
 211 #### Staying Up To Date
 212
 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:
 216
 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`
 232
 233 #### Submitting
 234
 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:
 238
 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.
 256
 257 ### With Git
 258
 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.
 264
 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)
 268
 269 Once you have a fork you may check it out:
 270
 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_.
 281
 282 It is preferred that your commits are signed using a PGP/GPG key, to enable
 283 this do the following:
 284
 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/>
 289
 290 After this you are ready to start development!
 291
 292 #### Starting A Branch
 293
 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:
 296
 297   * Checkout a new branch:
 298     * `git checkout -b wip-branch`
 299
 300 Please start your branch with `wip-` when making a branch!
 301
 302 #### Committing and Making Changes
 303
 304 When you are ready to commit your changes to your branch, you may do the
 305 following:
 306
 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`
 319
 320 #### Staying Up To Date
 321
 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:
 325
 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`
 337
 338 #### Submitting
 339
 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:
 343
 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_.
 348
 349 Alternatively a Git Bundle may be used:
 350
 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.