Add README files for some subprojects and update various other docs

Author: Gold856

CONTRIBUTING.md

@@ -18,7 +18,6 @@ So you want to contribute your changes back to WPILib. Great! We have a few cont
 - Tool suite changes must be generally useful to a broad range of teams
 - Excluding bug fixes, changes in one language generally need to have corresponding changes in other languages.
     - Some features, such the addition of C++23 for WPILibC or Functional Interfaces for WPILibJ, are specific to that version of WPILib only. New language features added to C++ must be wrappable in Python for [RobotPy](https://github.com/robotpy).
-    - Substantial changes often need to have corresponding LabVIEW changes. To do this, we will work with NI on these large changes.
 - Changes should have tests.
 - Code should be well documented.
     - This involves writing tutorials and/or usage guides for your submitted feature. These articles are then hosted on the [WPILib](https://docs.wpilib.org/) documentation website. See the [frc-docs repository](https://github.com/wpilibsuite/frc-docs) for more information.
@@ -30,12 +29,21 @@ So you want to contribute your changes back to WPILib. Great! We have a few cont
 - While we do welcome improvements to the API, there are a few important rules to consider:
     - Features must be added to Java (WPILibJ), C++ (WPILibC), with rare exceptions.
         - Most of Python (RobotPy) is created by wrapping WPILibC with pybind11 via robotpy-build. However, new features to the command framework should also be submitted to [robotpy-commands-v2](https://github.com/robotpy/robotpy-commands-v2) as the command framework is reimplemented in Python.
-    - During competition season, we will not merge any new feature additions. We want to ensure that the API is stable during the season to help minimize issues for teams.
+    - During competition season, we will not merge any new feature additions or removals. We want to ensure that the API is stable during the season to help minimize issues for teams.
     - Ask about large changes before spending a bunch of time on them! See [Contribution Process](#contribution-process) for where to ask.
     - Features that make it easier for teams with less experience to be more successful are more likely to be accepted.
     - Features in WPILib should be broadly applicable to all teams. Anything that is team specific should not be submitted.
     - As a rule, we are happy with the general structure of WPILib. We are not interested in major rewrites of all of WPILib. We are open to talking about ideas, but backwards compatibility is very important for WPILib, so be sure to keep this in mind when proposing major changes.
-    - Generally speaking, we do not accept code for specific sensors. We have to be able to test the sensor in hardware on the WPILib test bed. Additionally, hardware availability for teams is important. Therefore, as a general rule, the library only directly supports hardware that is in the Kit of Parts. If you are a company interested in getting a sensor into the Kit of Parts, please contact FIRST directly at frcparts@firstinspires.org.
+    - Generally speaking, we do not accept code for specific sensors. As a general rule, the library only directly supports hardware that is in the Kit of Parts. If you are a company interested in getting a sensor into the Kit of Parts, please contact FIRST directly at frcparts@firstinspires.org.
+
+### Design Philosophy
+
+WPILib's general design philosophy strays far away from the traditional Object-Oriented Programming architectures dominant in enterprise codebases. The general points to follow for WPILib are as follows:
+
+- Prefer functions and composition over inheritance. Inheritance is rigid and often prevents evolution, as adding or removing methods from an inherited class risks breakage. For similar reasons, functional interfaces (`std::function` in C++) are preferred over actual interfaces.
+- Avoid opaque black-boxes of functionality. Classes like RamseteCommand (removed in 2027) are good examples of this. While they look like a good abstraction that helps beginners, the black-box nature means they are [difficult to debug](https://github.com/wpilibsuite/allwpilib/issues/3350) and it's impossible to instrument the internals to figure out what's going on. Composition is strongly preferred, with documentation and examples describing how to do that composition.
+- Error at compile time, not runtime. Despite our best efforts, there will always be people who don't read stack traces (understandable for beginner programmers). Compile time errors show up in builds and in an IDE, which is much easier and faster for people to pinpoint and debug. Use language features to make invalid code impossible to build. The Matrix class in Java is an example of this. While clunky due to Java's weak generics system, it enforces correct Matrix dimensions at compile time, with the MatBuilder factory method throwing if the array passed in is the wrong size, which leads to the next point:
+- Try to only throw exceptions at code startup. Robots shouldn't quit, and it's a real "feels bad" moment when yours does, especially in a match. It's oftentimes better to have a robot continue running when it sees nonsensical state as opposed to outright crashing, since other components are often still functional. If you can't make invalid code a compile time error, throwing at the start of the robot program is the next best solution. This is typically done by throwing in constructors, or other functions likely to be called on code startup. But avoid throwing in functions likely to be called throughout a robot's runtime, e.g., in an `update` or `calculate` method, as again, crashing in the middle match is a terrible experience. Sometimes the behavior of functions are just incorrect if invalid data is passed in, and throwing is one of the only options. This is a judgement call, but if there are no options, throwing can be okay.
 
 ## Contribution Process
 

MAINTAINERS.md

@@ -1,5 +1,5 @@
 ## Publishing Third Party Dependencies
-Currently the 3rd party deps are imgui, opencv, google test, libssh, and apriltaglib
+Currently the 3rd party deps are imgui, opencv, google test, libssh, ceres, and gtsam.
 
 For publishing these dependencies, the version needs to be manually updated in the publish.gradle file of their respective repository.
 Then, in the azure build for the dependency you want to build for, manually start a pipeline build (As of current, this is the `Run Pipeline` button).
@@ -13,11 +13,8 @@ Note, changing artifact locations (This includes changing the artifact year curr
 ## Publishing allwpilib
 allwpilib publishes to the development repo on every push to main. To publish a release build, upload a new tag, and a release will automatically be built and published.
 
-## Publishing desktop tools
-Desktop tools publish to the development repo on every push to main. To publish a release build, upload a new tag, and a release will automatically be built and published.
-
 ## Publishing VS Code
-Before publishing, make sure to update the gradlerio version in `vscode-wpilib/resources/gradle/version.txt` Also make sure the gradle wrapper version matches the wrapper required by gradlerio.
+Before publishing, make sure to update the GradleRIO version in `vscode-wpilib/resources/gradle/version.txt` Also make sure the gradle wrapper version matches the wrapper required by GradleRIO.
 Upon pushing a tag, a release will be built, and the files will be uploaded to the releases on GitHub.
 
 ## Publishing GradleRIO

MavenArtifacts.md

@@ -18,27 +18,27 @@ The first types are Java artifacts. These are usually published as `jar` files.
 
 Example:
 ```
-edu.wpi.first.wpilibj:wpilibj-java:version
+org.wpilib.wpilibj:wpilibj-java:version
 ```
 
-The second types are native artifacts. These are usually published as `zip` files. The `-sources` and `-headers` classifiers contain the sources and headers respectively for the library. Each artifact also contains a classifier for each platform we publish. This platform is in the format `{os}{arch}`. The full list of supported platforms can be found in [native-utils](https://github.com/wpilibsuite/native-utils/blob/main/src/main/java/edu/wpi/first/nativeutils/WPINativeUtilsExtension.java#L94). If the library is built statically, it will have `static` appended to the classifier. Additionally, if the library was built in debug mode, `debug` will be appended to the classifier. The platform artifact only contains the binaries for a specific platform. Note that the binary artifacts never contain the headers, you always need the `-headers` classifier to get those.
+The second types are native artifacts. These are usually published as `zip` files. The `-sources` and `-headers` classifiers contain the sources and headers respectively for the library. Each artifact also contains a classifier for each platform we publish. This platform is in the format `{os}{arch}`. The full list of supported platforms can be found in [native-utils in the Platforms nested class](https://github.com/wpilibsuite/native-utils/blob/main/src/main/java/org/wpilib/nativeutils/WPINativeUtilsExtension.java). If the library is built statically, it will have `static` appended to the classifier. Additionally, if the library was built in debug mode, `debug` will be appended to the classifier. The platform artifact only contains the binaries for a specific platform. Note that the binary artifacts never contain the headers, you always need the `-headers` classifier to get those.
 
 If the library is Java and C++ and has a JNI component, the native artifact will have a shared library containing JNI entrypoints alongside the C++ shared library. This JNI shared library will have a `jni` suffix in the file name.
 
 Native artifacts are published with the base artifact name as their artifact ID, with a `-cpp` extension.
 
 Example:
 ```
-edu.wpi.first.wpimath:wpimath-cpp:version:classifier@zip
-edu.wpi.first.wpimath:wpimath-cpp:version:windowsx86-64staticdebug@zip
+org.wpilib.wpimath:wpimath-cpp:version:classifier@zip
+org.wpilib.wpimath:wpimath-cpp:version:windowsx86-64staticdebug@zip
 ```
 
 ## Provided Artifacts
 This repository provides the following artifacts. Below each artifact is its dependencies.
 
 For C++, if building with static dependencies, the listed order should be the link order in your linker.
 
-All artifacts are based at `edu.wpi.first.artifactname` in the repository.
+All artifacts are based at `org.wpilib.artifactname` in the repository.
 
 * wpiutil
 
@@ -52,32 +52,33 @@ All artifacts are based at `edu.wpi.first.artifactname` in the repository.
   * wpiutil
 
 * ntcore
-  * wpiutil
   * wpinet
+  * wpiutil
 
 * glass/libglass
-  * wpiutil
-  * wpimath
   * wpigui
+  * wpimath
+  * wpiutil
 
 * glass/libglassnt
-  * wpiutil
-  * wpinet
+  * wpigui
   * ntcore
+  * wpinet
   * wpimath
-  * wpigui
+  * wpiutil
 
 * hal
+  * ntcore
   * wpiutil
 
 * halsim
-  * wpiutil
-  * wpinet
+  * libglassnt
+  * libglass
   * ntcore
   * wpimath
   * wpigui
-  * libglass
-  * libglassnt
+  * wpinet
+  * wpiutil
 
 * cscore
   * opencv
@@ -126,12 +127,16 @@ All artifacts are based at `edu.wpi.first.artifactname` in the repository.
 
 ### Third Party Artifacts
 
-This repository provides the builds of the following third party software.
-
-All artifacts are based at `edu.wpi.first.thirdparty.frcYEAR` in the repository.
+This repository provides the builds of the following third party software:
 
-* apriltaglib
 * googletest
 * imgui
-* opencv
-* libssh
+
+Other software can be found in their corresponding GitHub repositories:
+
+* ceres: https://github.com/wpilibsuite/thirdparty-ceres
+* gtsam: https://github.com/wpilibsuite/thirdparty-gtsam
+* opencv: https://github.com/wpilibsuite/thirdparty-opencv
+* libssh: https://github.com/wpilibsuite/thirdparty-libssh
+
+All artifacts are based at `org.wpilib.thirdparty.frcYEAR` in the repository.

README-Bazel.md

@@ -1,10 +1,10 @@
 # WPILib Bazel Support
 
-WPILib is normally built with Gradle, but [Bazel](https://www.bazel.build/) can also be used to increase development speed due to the superior caching ability and the ability to use remote caching and remote execution (on select platforms)
+WPILib is normally built with Gradle, but [Bazel](https://www.bazel.build/) can also be used to increase development speed due to the superior caching ability and the ability to use remote caching and remote execution (on select platforms).
 
 
 ## Prerequisites
-- Install [Bazelisk](https://github.com/bazelbuild/bazelisk/releases) and add it to your path. Bazelisk is a wrapper that will download the correct version of bazel specified in the repository. Note: You can alias/rename the binary to `bazel` if you want to keep the familiar `bazel build` vs `bazelisk build` syntax.
+- Install [Bazelisk](https://github.com/bazelbuild/bazelisk/releases) and add it to your path. Bazelisk is a wrapper that will download the correct version of Bazel specified in the repository. Note: You can alias/rename the binary to `bazel` if you want to keep the familiar `bazel build` vs `bazelisk build` syntax.
 
 ## Building
 To build the entire repository, simply run `bazel build //...`. To run all of the unit tests, run `bazel test //...`
@@ -14,7 +14,7 @@ Other examples:
 - `bazel coverage //wpiutil/...` - (*Nix only) - Runs a code coverage report for both C++ and Java on all the targets under wpiutil
 
 ## User settings
-When invoking bazel, it will check if `user.bazelrc` exists for additional, user specified flags. You can use these settings to do things like always ignore buildin a specific folder, or limiting the CPU/RAM usage during a build.
+When invoking Bazel, it will check if `user.bazelrc` exists for additional, user specified flags. You can use these settings to do things like always ignore builds in a specific folder, or limiting the CPU/RAM usage during a build.
 Examples:
 - `build --build_tag_filters=-wpi-example` - Do not build any targets tagged with `wpi-example` (Currently all of the targets in wpilibcExamples and wpilibjExamples contain this tag)
 - `build -c opt` - Always build optimized targets. The default compiler flags were chosen to build as fast as possible, and thus don't contain many optimizations
@@ -36,12 +36,12 @@ Modify this to your likings if you want to build less.
 
 ## Pregenerating Files
 allwpilib uses extensive use of pre-generating files that are later used to build C++ / Java libraries that are tracked by version control. Quite often,
-these pre-generation scripts use some configuration file to create multipile files inside of an output directory. While this process could be accomplished
+these pre-generation scripts use some configuration file to create multiple files inside of an output directory. While this process could be accomplished
 with a `genrule` that would require an explicit listing of every output file, which would be tedious to maintain as well as potentially confusing to people
-adding new features those libraries. Therefor, we use `@aspect_bazel_lib` and their `write_source_files` feature to generate these directories. In the event that the generation process creates more than a small handful of predictable files, a custom rule is written to generate the directory.
+adding new features those libraries. Therefore, we use `@aspect_bazel_lib` and their `write_source_files` feature to generate these directories. In the event that the generation process creates more than a small handful of predictable files, a custom rule is written to generate the directory.
 
 ## Remote Caching
-One of the huge benefits of bazel is its remote caching ability. However, due to bazels strict build definitions it is hard to share remote cache artifacts between different computers unless our toolchains are fully hermetic, which means you are unlikely to be able to reuse the cache artifacts published from the `main` branch on your local machine like you might be able to with the `gradle` or `cmake` caches. Luckily the github actions CI machines are generally stable between runs and can reuse cache artifacts, and your local machine should remain stable, so if you set up a free buildbuddy account you can have your forks CI actions be able to use a personalized cache, as well as your local machine.
+One of the huge benefits of Bazel is its remote caching ability. However, due to Bazel's strict build definitions, it is hard to share remote cache artifacts between different computers unless our toolchains are fully hermetic, which means you are unlikely to be able to reuse the cache artifacts published from the `main` branch on your local machine like you might be able to with the `gradle` or `cmake` caches. Luckily, the GitHub Actions CI machines are generally stable between runs and can reuse cache artifacts, and your local machine should remain stable, so if you set up a free buildbuddy account you can have your forks CI actions be able to use a personalized cache, as well as your local machine.
 
 For the main `allwpilib` upstream, the cache is only updated on the main branch; pull requests from forks will not be able to modify the cache. However, you can set up your fork to enable its own cache by following the steps below.
 

README-CMake.md

@@ -5,16 +5,17 @@ WPILib is normally built with Gradle, however for some systems, such as Linux ba
 ## Libraries that get built
 * apriltag
 * cameraserver
+* commandsv2
 * commandsv3
 * cscore
+* datalog
 * fields
 * hal (simulation HAL only)
 * ntcore
 * romiVendordep
 * simulation extensions
 * wpigui
-* wpilib (wpilibc, wpilibj, and myRobot)
-* commandsv2
+* wpilib (wpilibc, wpilibj, and developerRobot)
 * wpimath
 * wpinet
 * wpiunits
@@ -26,6 +27,7 @@ WPILib is normally built with Gradle, however for some systems, such as Linux ba
 * glass
 * outlineviewer
 * sysid
+* wpical
 * halsim_gui (if simulation extensions are enabled)
 
 By default, all libraries get built with a default CMake setup. The libraries are built as shared libraries, and include the JNI libraries as well as building the Java JARs. Data Log Tool and the roboRIO Team Number Setter are only built if libssh is available.
@@ -89,7 +91,7 @@ If you want, you can also use `ccmake` in order to visually set these properties
 
 ## Presets
 
-The WPILib CMake setup has a variety of presets for common configurations and options used. The default sets the generator to Ninja and build directory to `build-cmake`. The other presets are `with-java` (sets `WITH_JAVA=ON`), `sccache` (sets the C/C++ compiler launcher to sccache), and `with-java-sccache` (a comibination of `with-java` and `sccache`.
+The WPILib CMake setup has a variety of presets for common configurations and options used. The default sets the generator to Ninja and build directory to `build-cmake`. The other presets are `with-java` (sets `WITH_JAVA=ON`), `sccache` (sets the C/C++ compiler launcher to sccache), and `with-java-sccache` (a combination of `with-java` and `sccache`).
 
 ## Building