Merge from trunk.

[SquirrelJME.git] / contributing.mkd

# Contributing

Before you contribute you should read and understand the [license](license.mkd)
that _SquirrelJME_ is under. You should abide by the
[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.

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

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](https://fossil-scm.org/) source control
system and as such it generally is expected that it is to be used. There also
are [GitHub Pull Requests](https://github.com/SquirrelJME/SquirrelJME/pulls)
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](test-writing.mkd) 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](
https://github.com/SquirrelJME/SquirrelJME/issues).

## 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](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

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](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`

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](
https://www.fossil-scm.org/xfer/doc/tip/www/quickstart.wiki).
 * [Fossil hints for users of Git](
https://www.fossil-scm.org/xfer/doc/trunk/www/gitusers.md).

#### 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](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_.

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](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:

 * 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.