jordan/SwerveIO
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
SwerveIO/README.md

6.5 KiB
Executable file
Raw Permalink Blame History

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

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.