Contributing

Home WebDemo Download JavaDoc Notes Timeline Branches Tags Tickets Wiki Login

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.

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.

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.

Core Code Contribution Requirements

  1. No AI generated code and/or AI sourced code.
    • If you are caught breaking this, you will be banned from the project and classified as a copyright violator with the intent of sabotage.
    • AI has no experience, has no intuition, and has no reasoning ability.
  2. No copy-and-paste of source code from other projects.
    • Other projects have different quality standards, rules, and what they expect. Just because one project is okay with it, means this project is.
    • Also, you have no idea what was going through their mind when they wrote that code along with the implications of it.
  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, fixing issues in SquirrelJME tends to be quicker and simpler because I know exactly where they happen.
  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.
    • Copying documentation verbatim is plagiarism and without writing it can you really say you truly understand what the code does?
  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. I love it when others respond that they find the code readable and easy to understand when they look at it, that 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, but 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!

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:

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.

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:

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:

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:

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:

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:

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

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

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

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:

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:

Alternatively a Git Bundle may be used:

This page was generated in about 0.03s by Fossil version [8be0372c10] 2024-04-23 13:25:26
Copyright © 2013-2019 Stephanie Gawroriski <xer@multiphasicapps.net>
Copyright © 2013-2019 Multi-Phasic Applications <http://multiphasicapps.net/>