Contributing to SquirrelJME

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.

Note that the project does not have an open-door contribution policy in place, as such there will be no encouragement for any developers. This passion and encouragement must only come from within. For clarification, your contribution may be rejected with no reason given.

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. For NanoCoat, CLion is recommended.

SquirrelJME values autonomy and self-determination.

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. Otherwise, it is recommended to send your patches via e-mail or by personal message.

Continue reading below for the contributing guide. Additionally, be sure to follow the Code Style Guidelines.

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.

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 or CodeBerg.

Core Code Contribution Requirements

  1. No AI generated code and/or AI sourced code.
    • AI currently is not permitted for the project.
    • If you violate this rule, you will be barred from the project at this time due to legal and copyright considerations.
  2. No copy-and-paste of source code from other projects.
    • Other projects have different quality standards, rules, and what they expect. This project has its own requirements on quality that do not match other projects.
  3. Fail-fast always, incomplete code/unknown state is a TODO, never no-op.
    • SquirrelJME aims for 99.9% accuracy, terminating the program with a TODO is an effective means of determining when an undefined state is about to be entered due to incomplete code. No-ops may allow programs to run a bit further, however they are extremely difficult to debug and fixing those issues takes much longer on average and requires deeper dives.
    • Being fail-fast, it has been observed that finding and fixing issues in SquirrelJME has been simplified as failure is caught sooner.
  4. Every method that gets implement gets JavaDoc (Java) or Doxygen (C), that is originally written by your own thoughts, not from an AI or copy/paste from existing documentation including through translation. Fully explain everything, including things which may be missing in the original documentation.
    • Please do not verbatim copy documentation from other sources without writing it yourself. It additionally helps to understand it as well.
  5. Comment code in recipe-like sections, every method is like a recipe that does something.
    • It simplifies the structure and logical operation of what a method is doing. It additionally sets barriers between logical recipe statements.
    • Write it for others and your future self.
    • A project with a quarter million lines of code is huge and gigantic, without any kind of logical structure at core logical levels the code would end up being an unmaintainable horrible mess. Please keep the project structure as it makes it easy to read and understand, this is a good thing.
  6. Do not trust inputs, always check inputs and always use exceptions and never assertions.
    • Yes documentation says that a method might only be called with values from one to ten, but you cannot trust a person to use said method correctly even if said person is yourself. You, myself, and everyone else is fallible, imperfect, and makes mistakes. It is better to check and fail always, than it is to continue.
    • Ignore static code analysis demanding that unused code be removed because the conditions will never be met.
    • This also makes debugging issues much easier.
    • Static code analysis might find a condition where code is unused, however it only knows of it from a single set or a few sets of state.

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:

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

You are however, free to give advice and insights! Just remember that this is clean room! Use of GenAI and/or LLMs is not considered clean room as these have been trained from unknown and/or unverified sources.

Contributor Agreement

ALL CONTRIBUTORS MUST ACCEPT THE FOLLOWING AGREEMENT BEFORE THEIR CODE WILL BE CONSIDERED FOR 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. THIS IS A LEGALLY BINDING CONTRACT.

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.
     a. You are not a contractor and/or third-party performing contracted
        work for the employer that the contribution is being made under.
     b. The contribution has been developed entirely in-house with no
        contractual labor and/or third-party labor.
     c. The employee making the contribution and interacting with the
        developers of SquirrelJME has significantly developed the
        contribution. It is not permitted for a manager, support person,
        Human Resources, coworker or otherwise to make the contribution
        on the employee's behalf.
     d. The employee continues to be employed and responsive while the
        review process is in progress.
     e. You have not ingested source code through an external service of
        which you do not have full copyright and patent ownership of.
 5.  Have pledged to follow the Code of Conduct.
 6.  Have read and understand the Contributor Ettiquite.
 7.  Understand that the code will be placed under the MPLv2.
 8.  Your contribution is not attached to any additional terms, terms of
     service, change of jurisdiction, regulatory requirements,
     and/or legal requirements.
     a. This includes terms which would require SquirrelJME to become
        beholden to a third-party.
 9.  Your contribution will not modify the software licenses,
     contributor agreement, copyright attribution/information,
     trademark information, and/or code of conduct.
     a. The only exception to this is an addition to the
        `third-party.mkd` licensing information, if an approved
        library is being now included in the source code.
 10. Have not used LLMs and/or GenAIs that do not strictly adhere to the
     project policy; at this time no such software is available, as such
     this is an effective ban on any and all LLM and/or GenAI use.
     a. This includes but is not limited to: Aider, ChatGPT, Claude,
        Codex, Copilot, Cursor, DeepSeek, Gemini, Junie, OpenClaw,
        OpenCode, and Windsurf.
     b. Models and Models as a Service (MaaS) of which:
        i.    You are a subscriber, sub-leaser, renter, trial member,
              member, patron, and/or shareholder.
        ii.   Have been trained on copyrighted, trademarked, and/or
              patented material; which is not in the public domain.
        iii.  There is a third-party arbitration cause in effect.
        iv.   You do not own the intellectual property rights to the model
              itself or the software which provides access to the model.
        v.    You are under contract to not be the sole owner of the model
              output.
        vi.   Have citations and content sources disabled, fully stripped,
              and/or intentionally limited via rule and/or prompt sets.
        vii.  Are unable to reproduce a prompt output/response
              deterministically utilizing the same input model and input
              data.
        viii. The model, source code, binary code, and/or software that
              provides access to the model has ingested and/or utilized
              output/responses from another Model or Model as a 
              Service (MaaS) which does not meet this criteria.
        ix.   The model, source code, binary code, and/or software that
              provides access to the model is not under a singular
              copyright or license.
        x.    The model, source code, binary code, and/or software that
              provides access to the model requires a subscription, service
              fee, membership, or other agreement such as a terms of
              service to access.
        xi.   The model, source code, binary code, and/or software that
              provides access to the model enforces access to an online
              service and is unable to be obtained through physical means
              such as a flash storage media, hard drive, compact disc, or
              magnetic storage media via international postage to be used
              for auditing and validation purposes.
        xii.  Requires large scale cloud based infrastructure to produce
              an output/response within a reasonable time, or requires
              hardware that is unreasonable to obtain. (Baseline hardware
              requirement is a Core i7-1370P, a mobile CPU with an Iris
              Xe Graphics GPU.)
        xiii. Does not have safeguards in place to prevent use outside of
              strict tool usage such as taking on a human persona or
              other fictional character.
        xiv.  Has not been vetted and approved by the developers of 
              SquirrelJME and Stephanie Gawroriski.

Committing and Submitting Changes

As previously stated, SquirrelJME is developed using Fossil. You may alternatively use Git along with and the Git mirrors, however this is not the official way to contribute to SquirrelJME and all contributions will go through Fossil always.

For reference, the two sections will accordingly be:

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.

Setup

Fossil is the recommended version control system.

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, however it is simple to use and works on Windows, Linux, and Mac OS X.

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):

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

After this you are ready to start development!

For reference, there are some guides for Fossil:

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.

Once you have a fork you may check it out:

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

After this you are ready to start development!

Starting A Branch

It is recommended that any development be done on branches and not on the mainline development tree.

With Fossil

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

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

With Git

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

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

Committing and Making Changes

Any changes you make should always be committed.

With Fossil

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

With Git

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

Staying Up To Date

As SquirrelJME is actively worked on, over time your repository will become out of date. Any development work that you perform should always be done on the latest code.

With Fossil

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:

With Git

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:

Submitting

All submissions to SquirrelJME should be sent in unified diff format. This is the traditional patch format that does not rely on any services or otherwise, it also means that your patch will be inline reviewed.

Always make sure that your branch and the trunk branch are up to date!

When submitting, you may send your patch via:

Note that your patch will be reviewed. You are expected to make the changes to the patch accordingly. If you fail to do so, then your patch will not be applied.

With Fossil

You can create a patch with the following command:

If you are on Windows or a system which lacks diff, you may need to also specify:

With Git

You can create a patch with the following command:

Reviewing

When your patch is reviewed, comments will be placed inline within the patch, then it will be sent back to you. The start of line will use the # character, which should be ignored by patch utilities. An example of an inline review:

Index: contributing.mkd
==================================================================
--- contributing.mkd
+++ contributing.mkd
@@ -188,28 +188,32 @@
                library is being now included in the source code.
 
 ## 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
# This is an example comment on a patch, please make any changes that are
# requested.
-would like to stick to something more familiar then you may also as well use
-[Git](https://git-scm.com/).
+[Fossil](https://fossil-scm.org/). You may alternatively use Git along with
+and the Git mirrors, however this is not the official way to contribute to
+_SquirrelJME_ and all contributions will go through Fossil always.
This page was generated in about 0.057s by Fossil version [1205ec86cb] 2025-04-30 16:57:32
Copyright © 2013-2025 Stephanie Gawroriski <xer@multiphasicapps.net>
Copyright © 2013-2025 Multi-Phasic Applications <http://multiphasicapps.net/>