SwerveIO/README.md

SwerveIO
========

The Open Source Swerve Drive Library
------------------------------------

SwerveIO is an open-source swerve drive library written for FRC in Java.
It is pronounced "Swerve - ee - oh", which rhymes with "Oreo".

You are currently viewing the **developer documentation**. The upstream
user documentation is available as JavaDoc documentation in the source
tree and can be easily generated using the `javadoc` Gradle task. The
change log is available below.

Project Status
--------------

I am no longer on an FRC team, and my old FRC team refuses to use
SwerveIO anymore. Suffice it to say that SwerveIO's future doesn't look
too good. That being said, if you are interested in SwerveIO, please
reach out to me and let me know. I am more than happy to keep working
on SwerveIO, but right now I don't see a lot of interest, so I don't
want to waste my time on it.

This project is as good as dead, but it doesn't have to be! Seriously,
an email telling me you want to see this thing going again is all it
would take. Until I get that email though, you likely won't see any
changes to this code. This message was written on February 17, 2022.

Project Layout
--------------

This project is a standard Gradle project with multiple subprojects. It
strives to follow the Gradle-prescribed file system hierarchy as closely
as possible.

Building
--------

SwerveIO can be built using a simple `./gradlew build`. Documentation
can be built with `./gradlew javadoc`. If you don't have an internet
connection or are at a competition, you can specify the `--offline`
Gradle flag. This will speed up builds dramatically because a lot of
non-essential functionality will be disabled.

Contributing
------------

The contribution workflow for SwerveIO may be different from what you
might be used to. Please see my [homepage](http://bancino.net) for
instructions.

SwerveIO is a highly specialized library designed to meet the
programming standards enforced by the style recommendations for the Java
language. The
[Google Style Guide](https://google.github.io/styleguide/javaguide.html)
is a good guide to follow, however exact standards enforced in this
library will be at the discretion of its maintainers. I personally just
use my IDE's formatting tool call it good. I do, however, have the
following rules specific to this project:

*   Always explicitly declare the type of a variable, even in lambda
    expressions. In other words, don't use the `var` keyword, and if you
    have a lambda that looks like this:
    `(param) -> doSomethingWith(param)`, change it to this:
    `(String param) -> doSomethingWith(param)`, where `String` is the
    actual type of `param`.

The goal for SwerveIO is to be the best possible library that can be
used by the most people. Contributors should write their highest quality
code. This means that SwerveIO should be:

*   **Stable:** SwerveIO should work consistently no matter what.
    Whenever possible, the public-facing API should be preserved so that
    users can upgrade without much difficult. Additionally, every
    individual release should perform consistently every time.
*   **Standardized:** All the Java sandards should be followed. This is
    a Java library, it should look and work like one.
*   **Efficient:** Code should be clean and efficient.
*   **Versatile:** Remember that the design goals of SwerveIO intend to
    cater to the most swerve drive users as possible. Code should not be
    specialized or dependent on any hardware or 3rd-partly library
    behavior when possible. Great care has been taken to ensure the
    library is abstract enough that new hardware can be easily added.
*   **Documented:** Always keep the documentation up to date and write
    comments wherever they are needed. Currently, there are more lines
    of comment in SwerveIO than there are lines of code. I am proud of
    that.

Before contributing to the development of SwerveIO, please be sure of
the following:

*   You accept the terms of the license that your contributions will be
    released under. See the `LICENSE` file.
*   You agree to the contributor code of conduct, detailed below.
*   You took a look at the `TODO` file. That file contains what's
    planned for the future of SwerveIO, so maybe you can help out with
    some of the items listed there.

When making your changes, be sure to add an appropriate entry to the
changelog.

Environment Setup
-----------------

You need the following pieces of software to develop and contribute to
SwerveIO:

*   A Java Development Kit (JDK), version 11 or greater
*   CVS 
*   An IDE or text editor

I don't have any hard requirements for the IDE or text editor you use,
but I would highly recommend using VSCode or IntelliJ because I have
both configurations bundled to set up the project automatically for you.

Code of Conduct
---------------

SwerveIO's development code of conduct is simple:

*   Be human. We're all people here and we may all be different and at
    different stages of life. Be understanding of others and know that
    they may be going through something you aren't aware of.
*   Don't get political. There is a place for politics, and if you know
    me personally, you know I am quite opinionated. But SwerveIO's
    development cycle is not the place for politics. The focus should
    just be on writing code with fellow programmers and helping to
    create the best library possible.

Release Checklist
-----------------

This is just to help me when I'm releasing new versions of SwerveIO.

*    Increment version in `build.gradle`
*    Add changelog entry to this readme.
*    Tag the release with the version number and publish it to my
     website.

Release Model
-------------

SwerveIO may be under heavy development during robotics seasons. Because
of this, it featured an aggressive release model in its early days that
wasn't afraid to break existing code. However, as I want SwerveIO to be
stable, and I have grown more conservative over the years, I want to
slow things down and keep things stable. I am open to the idea of
maintaining long term support (LTS) releases along side the primary
development cycle. I want SwerveIO to work for its users, so please
contact me so we can discuss SwerveIO's release model.

SwerveIO strives to adhere to [Semantic Versioning](https://semver.org):

> Given a version number MAJOR.MINOR.PATCH, increment the:
> 
> 1.  MAJOR version when you make incompatible API changes,
> 2.  MINOR version when you add functionality in a backwards compatible
>     manner, and
> 3.  PATCH version when you make backwards compatible bug fixes.