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.

Change Log
----------

8.0.2
-----

- Updated the contributing instructions to note the usage of CVS
  instead of Git.
- Added a notice to this README announcing the deprecation of SwerveIO.
  I'm sad to see this project go, and maybe I'll revive it at some
  point later in life, but if nobody expresses any interest in what
  I've done here, then I'll lay this project to rest. I'll of course
  still host all the source code here, and if you're considering forking
  SwerveIO, I'd say reach out to me and email me because I want to be
  involved!

**Note:** This release makes no code or build changes. It simply bumps
the version number so that I could update this README. For that reason,
I have no idea if SwerveIO still builds with current tooling, but I know
that if for some reason it doesn't, we can get it going again in no
time, just send me an email.

8.0.1
-----

- Updated CTRE Phoenix to the latest kickoff release. This fixes a build
  error that some Windows users were encountering when trying to build
  against the local Maven repository.

8.0.0
-----

Welcome to the 2022 Kickoff! This release includes all the  changes
from `8.0.0-rc1` and `8.0.0-rc2`, so if you're upgrading from SwerveIO
7x, make sure to read the release notes for those too!

- Updated WPILib to '2022.1.1', the kickoff release of WPILib.
- Upgraded the SparkMax API to REVLib 2022.
    - The `SparkMaxEncoder` class constructors were updated to reflect
      the changes made to how REV does encoders. Some breaking changes
      were made for users that weren't using the default constructor. If
      you were using the default constructor, you should notice no
      changes.
- Removed the `LegacySpeedController` class introduced in `-rc1` because
  all vendors now support WPILib's `SpeedController`.

8.0.0-rc2
---------

- Updated WPILib to `2022.1.1-rc-1`.
- Updated OpenCV to `4.5.2-1`.
- Made some internal variables `final`.

SwerveIO 8.0.0 will be released when WPILib 2022.1.1 is, which will
most likely occur before or during the 2022 kickoff. At this time, I
am considering breaking all WPILib support off into a separate Gradle
subproject, because of the recent breaking changes. SwerveIO will still
fully support WPILib, but will also provide all its own interfaces so
that it can be used entirely separate if necessary.

8.0.0-rc1
---------

SwerveIO 8x brings SwerveIO up to date with WPILib 2022.x. This release
should look a lot like the previous releases. However, WPILib made a lot
of breaking user-facing API changes. This update is simply to reflect
those changes and make  SwerveIO compatible with future releases of
WPILib and vendor libraries.

**Note:** This release of SwerveIO is not compatible with WPILib 2021 or
earlier. It *requires* WPILib 2022.1.1 or later.

The breaking changes are as follows:

*   Replaced all references to the deprecated `SpeedController`
    with the new `MotorController`. All interfaces and implementations
    were adjusted accordingly.

Other non-breaking changes are also included in this release:

*   Replaced a reference to the deprecated `DriverStation.getInstance()`
    with just `DriverStation`.
*   Added the `LegacySpeedController` class to support vendor APIs that
    haven't updated their APIs to use the latest WPILib. Note that this
    class is already deprecated and schedule for removal as soon as all
    supported hardware vendors update their APIs or WPILib removes the
    `SpeedController` interface, whichever happens first.
*   Cleaned up this README document to reflect the current state of
    SwerveIO.
*   Updated the copyright headers throughout the code.

7.0.4
-----

*   Updated the IntelliJ configuration to use the system's JDK instead
    of a hard-coded JDK.
*   Updated Gradle from `7.2` to `7.3.3`.
*   Updated WPILib to `2022.1.1-beta-4`.
*   `[vendor/kauai]` Updated NavX library to `4.0.435`.
*   As far as I can tell, it looks like CTRE Phoenix is working again.
    As of the date of this release, SwerveIO can be built normally.

7.0.3
-----

*   Added an IntelliJ `.idea` folder for developing SwerveIO with
    IntelliJ. Since I'm no longer on the robotics team, I don't use VS
    Code much anymore, so I've become much more familiar with IntelliJ.
    Obviously IntelliJ cannot be used by students, because students
    require the WPILib VS Code plugins, but since I'm not going to be
    directly deploying SwerveIO to a robot, I can use IntelliJ.
*   Updated Gradle from 7.1.1 to 7.2.
*   Updated CTRE Phoenix from 5.19.4 to 5.20.0. Note that at this time,
    neither version will build with SwerveIO because the CTRE Maven
    repository is broken. It does not match what is in the vendor JSON
    description file, and indexing is not allowed, so I'm unable to
    troubleshoot. If anyone knows what's up with this, or has a fix,
    please contact me at
    [jordan@bancino.net](mailto:jordan@bancino.net).
*   Documented the LogIO classes.

7.0.2
-----

Updated Gradle from 7.0.1 to 7.1.1, and fixed some broken links.

7.0.1
-----

Fixed some errors in the Javadoc home page that prevented the
documentation from building correctly on JDK 11.

7.0.0
-----

SwerveIO 7.0.0 cleans up a lot of the API, making for neater and less
fragmented code. This release also simplifies the build system and
documentation, and attempts to decouple both from Jordan Bancino's
infrastructure so that SwerveIO is fully self-contained.

*   Removed all methods and classes that were deprecated as of the
    previous release.
*   Removed all kit module constructors that referenced angle offsets,
    because angle offsets are now handled at the `SwerveDrive` level
    using `saveAngleOffsets()` and `loadAngleOffets()`
*   Merge LogIO directly into the SwerveIO source tree. LogIO is now a
    part of SwerveIO Core, instead of being it's own artifact. The
    package name will stay the same and this change will be reversed if
    LogIO becomes needed for future projects.
*   Update dependencies:
    *   **Gradle:** 7.0 -> 7.0.1

6.1.2
-----

This release doesn't make any changes directly to SwerveIO; it is simply
a dependency update:

*   **WPILib:** 2021.2.2 -> 2021.3.1
*   **Gradle:** 6.8.3 -> 7.0
    *   JCenter is being shut down, so now certain dependencies are 
        loaded from Maven Central.