jordan/SwerveIO
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
SwerveIO/README.md
Jordan Bancino e594f42c69 Initial import from CVS.
2024-01-02 18:14:26 -05:00

323 lines
13 KiB
Markdown
Executable file
Raw 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](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.
Reference in a new issue View git blame Copy permalink