From bb64dd3546c6d9edc9c670f99ebe915b394053c8 Mon Sep 17 00:00:00 2001 From: Fredric Silberberg Date: Tue, 10 May 2016 11:15:13 -0400 Subject: [PATCH] Updated README, and added in CONTRIBUTING. This adds tables of contents, as well as fixing a few other issues. --- CONTRIBUTING.md | 56 +++++++++++++++++++ README.md | 47 +++++++++++----- ...License_for_WPILib_code.txt => license.txt | 0 3 files changed, 89 insertions(+), 14 deletions(-) create mode 100644 CONTRIBUTING.md rename BSD_License_for_WPILib_code.txt => license.txt (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..0d946875ee --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing to WPILib + +So you want to contribute your changes back to WPILib. Great! We have a few contributing rules that will help you make sure your changes will be accepted into the project. Please remember to follow the rules written here, and behave with Gracious Professionalism. + +- [General Contribution Rules](#general-contribution-rules) +- [What to Contribute](#what-to-contribute) +- [Coding Guidelines](#coding-guidelines) +- [Submitting Changes](#submitting-changes) + - [Pull Request Format](#pull-request-format) + - [Merge Process](#merge-process) +- [Licensing](#licensing) + +## General Contribution Rules + +- Everything in the library must work for the 3000+ teams that will be using it. +- We need to be able to maintain submitted changes, even if you are no longer working on the project. +- 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++11 for WPILibC or Functional Interfaces for WPILibJ, are specific to that version of WPILib only. + - 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 often involves ScreenSteps. To add content to ScreenSteps, we will work with you to get the appropriate articles written. + +## What to Contribute + +- Bug reports and fixes + - We will generally accept bug fixes without too much question. If they are only implemented for one language, we will implement them for any other necessary languages. Bug reports are also welcome, please submit them to our GitHub issue tracker. +- While we do welcome improvements to the API, there are a few important rules to consider: + - Features must be added to both WPILibC and WPILibJ, with rare exceptions. + - 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. + - Ask about large changes before spending a bunch of time on them! You can create a new issue on our GitHub tracker for feature request/discussion and talk about it with us there. + - 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. + +## Coding Guidelines + +WPILib uses Google style guides for both C++ and Java. Autoformatters are available for many popular editors at [https://github.com/google/styleguide]. An online version of the styleguide for [C++](https://google.github.io/styleguide/cppguide.html) and [Java](https://google.github.io/styleguide/javaguide.html) are also available. Additionally, offline copies of the style guide can be found in the style guide directory of the repository. + +While the library should be fully formatted according to the styles, additional elements of the style guide were not followed when the library was initially created. All new code should follow the guidelines. If you are looking for some easy ramp-up tasks, finding areas that don't follow the style guide and fixing them is very welcome. + +## Submitting Changes + +### Pull Request Format + +Changes should be submitted as a Pull Request against the master branch of WPILib. For most changes, we ask that you squash your changes down to a single commit. For particularly large changes, multiple commits are ok, but assume one commit unless asked otherwise. No change will be merged unless it is up to date with the current master. We will also not merge any changes with merge commits in them; please rebase off of master before submitting a pull request. We do this to make sure that the git history isn't too cluttered. + +### Merge Process + +When you first submit changes, Travis-CI will attempt to run `./gradlew check` on your change. If this fails, you will need to fix any issues that it sees. Once Travis passes, we will begin the review process in more earnest. One or more WPILib team members will review your change. This will be a back-and-forth process with the WPILib team and the greater community. Once we are satisfied that your change is ready, we will allow our Jenkins instance to test it. This will run the full gamut of checks, including integration tests on actual hardware. Once all tests have passed and the team is satisfied, we will merge your change into the WPILib repository. + +## Licensing + +By contributing to WPILib, you agree that your code will be distributed with WPILib, and licensed under the license for the WPILib project. You should not contribute code that you do not have permission to relicense in this manner. This includes code that is licensed under the GPL that you do not have permission to relicense, as WPILib is not released under a copyleft license. Our license is the 3-clause BSD license, which you can find [here](license.txt). \ No newline at end of file diff --git a/README.md b/README.md index 08269834d5..50985a8c95 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,23 @@ +# WPILib Project + +Welcome to the WPILib project. This repository contains the HAL, WPILibJ, and WPILibC projcts. These are the core libraries for creating robot programs for the roboRIO. + +- [WPILib Mission](#wpilib-mission) +- [Building WPILib](#building-wpilib) + - [Requirements](#requirements) + - [Setup](#setup) + - [Building](#building) + - [Publishing](#publishing) + - [Structure and Organization](#structure-and-organization) +- [Contributing to WPILib](#contributing-to-wpilib) + +## WPILib Mission + +The WPILib Mission is to enable FIRST Robotics teams to focus on writing game-specific software rather than focussing on hardware details - "raise the floor, don't lower the ceiling". We work to enable teams with limited programming knowledge and/or mentor experience to be as successful as possible, while not hampering the abilities of teams with more advanced programming capabilities. We support Kit of Parts control system components directly in the library. We also strive to keep parity between major features of each language (Java, C++, and NI's LabVIEW), so that teams aren't at a disadvantage for choosing a specific programming language. WPILib is an open source project, licensed under the BSD 3-clause license. You can find a copy of the license [here](license.txt). + # Building WPILib -Building WPILib is very straightforward. WPILib uses Gradle to compile. It only has a few dependencies on outside tools, including the ARM cross compiler. +Using Gradle makes building WPILib very straightforward. It only has a few dependencies on outside tools, such as the ARM cross compiler for creating roboRIO binaries. ## Requirements - [ARM Compiler Toolchain](http://first.wpi.edu/FRC/roborio/toolchains/) @@ -10,27 +27,26 @@ Building WPILib is very straightforward. WPILib uses Gradle to compile. It only Clone the WPILib Repo. If the toolchains are not installed, install them, and make sure they are available on the system PATH. ## Building -All build steps are executed using the Gradle wrapper, `gradlew`. Each target that Gradle can build is referred to as a task. The most common Gradle task to use is `build`. This will build all of the outputs created by WPILib. To run, open a console and cd into the cloned WPILib directory. Then: +All build steps are executed using the Gradle wrapper, `gradlew`. Each target that Gradle can build is referred to as a task. The most common Gradle task to use is `build`. This will build all the outputs created by WPILib. To run, open a console and cd into the cloned WPILib directory. Then: ```bash ./gradlew build ``` -To build a specific subproject, such as wpilibc, you must access the subproject and run the build task only on that project. Accessing a subproject in Gradle is quite easy. Simply use `:subproject_name:task_name` with the Gradle wrapper. For example, building just wpilibc: +To build a specific subproject, such as WPILibC, you must access the subproject and run the build task only on that project. Accessing a subproject in Gradle is quite easy. Simply use `:subproject_name:task_name` with the Gradle wrapper. For example, building just WPILibC: ```bash ./gradlew :wpilibc:build ``` -If you also want simulation to be build, add -PmakeSim. This requires gazebo_transport. We have tested on 14.04 and 15.05, but any correct install of gazebo should work, even on windows if you build from source. Correct means cmake needs to be able to find gazebo-config.cmake, which you get for free with ubuntu installs. +If you also want simulation to be built, add -PmakeSim. This requires gazebo_transport. We have tested on 14.04 and 15.05, but any correct install of Gazebo should work, even on Windows if you build Gazebo from source. Correct means CMake needs to be able to find gazebo-config.cmake. See [The Gazebo website](https://gazebosim.org/) for installation instructions. ```bash ./gradlew build -PmakeSim ``` -C++ simulation tasks (including plugins, gz_msgs, and wpilibcSim) all depend on gazebo_transport. In order for this to build you must have installed gazebo. See [The Gazebo website](https://gazebosim.org/) for installation instructions. If you prefer to use CMake directly, the you can still do so. -The common cmake tasks are wpilibcSim, frc_gazebo_plugins, and gz_msgs +The common CMake tasks are wpilibcSim, frc_gazebo_plugins, and gz_msgs ```bash mkdir build #run this in the root of allwpilib @@ -39,13 +55,12 @@ cmake .. make ``` - -The gradlew wrapper only exists in the root of the main project, so be sure to run all commands from there. All of the subprojects have build tasks that can be run. Gradle automatically determines and rebuilds dependencies, so if you make a change to the HAL and then run `:wpilibc:build`, the HAL will be rebuilt, then wpilibc. +The gradlew wrapper only exists in the root of the main project, so be sure to run all commands from there. All of the subprojects have build tasks that can be run. Gradle automatically determines and rebuilds dependencies, so if you make a change in the HAL and then run `./gradlew :wpilibc:build`, the HAL will be rebuilt, then WPILibC. There are a few tasks other than `build` available. To see them, run the meta-task `tasks`. This will print a list of all available tasks, with a description of each task. ## Publishing -If you are building to test with the eclipse plugins or just want to export the build as a Maven-style dependency, simply run the `publish` task. This task will publish all available packages to ~/releases/maven/development. If you need to publish the project to a different repo, you can specify it with `-Prepo=repo_name`. Valid options are: +If you are building to test with the Eclipse plugins or just want to export the build as a Maven-style dependency, simply run the `publish` task. This task will publish all available packages to ~/releases/maven/development. If you need to publish the project to a different repo, you can specify it with `-Prepo=repo_name`. Valid options are: - development - The default repo. - beta - Publishes to ~/releases/maven/beta. @@ -54,20 +69,24 @@ If you are building to test with the eclipse plugins or just want to export the The following maven targets a published by this task: -- edu.wpi.first.wpilib.cmake:cpp-root:1.0.0 - RoboRIO C++ +- edu.wpi.first.wpilib.cmake:cpp-root:1.0.0 - roboRIO C++ - edu.wpi.first.wpilibc.simulation:WPILibCSim:0.1.0 - Simulation C++ -- edu.wpi.first.wpilibj:wpilibJavaFinal:0.1.0-SNAPSHOT - RoboRIO Java +- edu.wpi.first.wpilibj:wpilibJavaFinal:0.1.0-SNAPSHOT - roboRIO Java - edu.wpi.first.wpilibj:wpilibJavaSim:0.1.0-SNAPSHOT - Simulation Java - edu.wpi.first.wpilibj.simulation:SimDS:0.1.0-SNAPSHOT - The driverstation for controlling simulation. - org.gazebosim:JavaGazebo:0.1.0-SNAPSHOT - Gazebo protocol for Java. ## Structure and Organization -The main wpilib code you're probably looking for is in wpilibj and wpilibc. Those directories are split into shared, sim, and athena. Athena contains the wpilib code meant to run on your RoboRIO. Sim is wpilib code meant to run on your computer with gazebo, and shared is code shared between the two. Shared code must be platform-independent, since it will be compiled with both the ARM cross-compiler and whatever desktop compiler you are using (g++, msvc, etc...). +The main WPILib code you're probably looking for is in WPILibJ and WPILibC. Those directories are split into shared, sim, and athena. Athena contains the WPILib code meant to run on your roboRIO. Sim is WPILib code meant to run on your computer with Gazebo, and shared is code shared between the two. Shared code must be platform-independent, since it will be compiled with both the ARM cross-compiler and whatever desktop compiler you are using (g++, msvc, etc...). The Simulation directory contains extra simulation tools and libraries, such as gz_msgs and JavaGazebo. See sub-directories for more information. The integration test directories for C++ and Java contain test code that runs on our test-system. When you submit code for review, it is tested by those programs. If you add new functionality you should make sure to write tests for it so we don't break it in the future. -The hal directory contains more C++ code meant to run on the RoboRIO. HAL is an acronym for "Hardware Abstraction Layer", and it interfaces with the NI Libraries. The NI Libraries contain the low-level code for controlling devices on your robot. The NI Libraries are found in the ni-libraries folder. +The hal directory contains more C++ code meant to run on the roboRIO. HAL is an acronym for "Hardware Abstraction Layer", and it interfaces with the NI Libraries. The NI Libraries contain the low-level code for controlling devices on your robot. The NI Libraries are found in the ni-libraries folder. -The styleguide directory contains the styleguide for C++ and Java code. Anything submitted to the wpilib project needs to follow the code style guides outlined in there. \ No newline at end of file +The styleguide directory contains the styleguide for C++ and Java code. Anything submitted to the WPILib project needs to follow the code style guides outlined in there. For details about the style, please see the contributors document [here](CONTRIBUTING.md#coding-guidelines). + +# Contributing to WPILib + +See [CONTRIBUTING.md](CONTRIBUTING.md). \ No newline at end of file diff --git a/BSD_License_for_WPILib_code.txt b/license.txt similarity index 100% rename from BSD_License_for_WPILib_code.txt rename to license.txt