Contributing

Before you contribute you should read and understand the license that SquirrelJME is under. You should abide by the Code of Conduct, 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.

• For instructions on building, see the building guide.
• If you wish to maintain or become a maintainer please read the developer guide!

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.

SquirrelJME uses the Fossil source control system and as such it generally is expected that it is to be used. There also are GitHub Pull Requests 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. Any pull requests made on GitHub will be converted to Fossil then merged in accordingly.

Continue reading below for the contributing guide.

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 reformatting/refactoring files.
  • 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.
• If any code is incomplete, for any execution path that leads to incomplete code then Debugging.todo() must be used so that such incomplete code is fail-fast and prevents continued operation.
• New code must have tests implemented, following the guide in the Test Writing document.
• 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.
• 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.
  • You can run all the tests with the gradlew testHosted and gradlew testSpringCoat command.
• 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.
• The trunk branch is always stable code. It must always pass and be in a state of release!
• 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.

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.

Exceptions to Contributing

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:

• Apache:
  • Apache Harmony
• Free Software Foundation:
  • GNU Compiler for Java (GCJ)
  • GNU Classpath
  • GNU Interpreter for Java (GIJ)
• Google:
  • Android
• IBM:
  • OpenJ9
• Microsoft:
  • Microsoft Java Virtual Machine (MSJVM)
• Oracle/Sun Microsystems:
  • HotSpot
  • Java (eventually became OpenJDK)
  • OpenJDK and any of its variants
  • PhoneME

Additionally, for legal purposes, code that is derived from the source code from these projects cannot be used.

Contributor Agreement

ALL CONTRIBUTORS MUST ACCEPT THE FOLLOWING AGREEMENT BEFORE THEIR CODE WILL 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.

You grant Stephanie Gawroriski an irrevocable license that:

 1. That you own the contributing work.
 2. Grants a patent license, as per the Mozilla Public License 2.0.
 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.
 4. If employed by a company, you have a right by that company to provide
    contributions to this project.
 5. Have pledged to follow the Code of Conduct.
 6. Have read and understand the Ettiquite.

Committing and Submitting Changes

As previously stated, SquirrelJME is developed using Fossil 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.

For reference, the two sections will accordingly be:

• With Fossil
• With Git

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.

With Fossil

SquirrelJME uses Fossil 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.

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

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

After this you are ready to start development!

For reference, there are some guides for Fossil:

• Fossil quick-start guide.
• Fossil hints for users of Git.

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:
  • fossil branch new wip-branch trunk
• Switching to that branch:
  • fossil update wip-branch

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

Committing and Making Changes

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:
    • fossil update wip-branch
  • 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:
  • fossil bundle export wip-branch.bun --branch wip-branch --standalone
• 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.
    • 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.

With Git

Although SquirrelJME does not use Git there are mirrors to both GitHub and GitLab. 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
  • GitLab

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.

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

• Please read the following guides:
  • 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/

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:
  • git checkout -b wip-branch

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

Committing and Making Changes

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

• 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!
• 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:
    • git push --set-upstream origin wip-branch

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:

• Checkout the trunk branch:
  • git checkout trunk
• Pull in the latest changes:
  • git pull
• Checkout your branch:
  • git checkout wip-branch
• 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

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:
  • Create a Pull Request.
• Via GitLab:
  • Create a Merge Request.

Alternatively a Git Bundle may be used:

• Create a patch bundle for your branch:
  • git format-patch --binary --stdout --attach -n trunk..wip-branch > wip-branch.bun
• Send a copy of this patch 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.
    • 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.