160 lines
6.5 KiB
Markdown
Executable file
160 lines
6.5 KiB
Markdown
Executable file
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.
|