From b5277e5f4c7c0b024d594cfb53d3ead5b3466dcd Mon Sep 17 00:00:00 2001 From: Chris Gerth Date: Thu, 26 Mar 2026 21:32:17 -0500 Subject: [PATCH] Add Community Contribution Guidelines (#2405) ## Description Leadership team identified gaps in how we introduce new developers to the community. Additional docs for onboarding new developers, helping clarify roles and what counts as a "good" PR. ## Meta Merge checklist: - [ X] Pull Request title is [short, imperative summary](https://cbea.ms/git-commit/) of proposed changes - [ X] The description documents the _what_ and _why_, including events that led to this PR - [ ] If this PR changes behavior or adds a feature, user documentation is updated - [ ] If this PR touches photon-serde, all messages have been regenerated and hashes have not changed unexpectedly - [ ] If this PR touches configuration, this is backwards compatible with all settings going back to the previous seasons's last release (seasons end after champs ends) - [ ] If this PR touches pipeline settings or anything related to data exchange, the frontend typing is updated - [ ] If this PR addresses a bug, a regression test for it is added - [ ] If this PR adds a dependency, the license has been checked for compatibility and steps taken to follow it --- docs/source/docs/contributing/guidelines.md | 68 +++++++++++++++++++++ docs/source/docs/contributing/index.md | 1 + 2 files changed, 69 insertions(+) create mode 100644 docs/source/docs/contributing/guidelines.md diff --git a/docs/source/docs/contributing/guidelines.md b/docs/source/docs/contributing/guidelines.md new file mode 100644 index 000000000..53873e62c --- /dev/null +++ b/docs/source/docs/contributing/guidelines.md @@ -0,0 +1,68 @@ +# Welcome! + +First and foremost, welcome to PhotonVision Development! We're pumped that you're interested to jump in, and help out! + +Like most things in FIRST, PhotonVision is reliant on the hard work of dedicated volunteers. It doesn't exist without you. You're joining in with a strong tradition of open-source software development. + +This page talks a bit about how we develop PhotonVision, as a community. It applies to all repos and community aspects for PhotonVision. + +## Getting Started + +The very first thing we'd recommend - get your computer set up to be able to build and run PhotonVision. [Docs for that are here](building-photon.md). + +The two best ways to figure out what to do first: + +1. Take a look at [the main PhotonVision Repo's Issues](https://github.com/PhotonVision/photonvision/issues) - especially those marked `bug` or `good first issue`! +2. Connect on [the Discord Server](https://discord.gg/wYxTwym) - Introduce yourself, and talk about what you're interested in! + +From there - assign yourself to an issue if you intend to work it. Create a Fork in github, and make and test your changes. Once passing builds, meeting your expectations, and passing CI, open a pull request back to the main repo. + +## Submitting A PR + +Pull Requests are the mechanism used to ensure we only merge high-quality, reviewed, concrete, and organized changes to the codebase. + +Things that peer reviewers will look for include: + +* All CI checks are passing on the server. +* Documentation - does the PR match the issue? Is the description detailed? +* Cohesiveness - does the PR express a singular, related set of changes? +* Architecture - is the code consistent with other code around it? Is it maintainable for the long term? +* Testing - have unit tests been added as appropriate? Has the change been tested on real hardware? + +Work as you can to clean up any changes requested. Once all changes are addressed, the contain should get merged, and included in the next release! Horary! + +## General Developer Interaction + +The main guiding principle: remember that we're all volunteers. While promptness is always appreciated (and occasionally required as release deadlines approach), it's important to remember each individual is only contributing when their personal schedule allows. Expect delays, prefer asynchronous communication, and be polite with reminders. + +While most of the community members are either FIRST robotics mentors or students, the PhotonVision development team is primarily focused on delivering high quality software. Mentorship can and does occur, but is not the primary goal. Members are expected to do their learning fairly independently. + +Seek to build trust in the quality of your work. Think carefully on your opinions before asking others to think about them too. + +Bias toward action, and productionizable code. Limit the number of active PR's to help keep focus. + +Finally, be sure to embody the ethos of Gracious Professionalism in all your actions, on all platforms in the project. See more in our [code of conduct](https://github.com/PhotonVision/.github/blob/738dfcb792fdbfc2e8408c0135e389179fc483c0/codeofcoduct.md) + +### AI Usage + +Coding assistants driven by Large Language Models ("AI") are extremely powerful tools, and have been used on more than one occasion to accelerate development. + +PhotonVision still maintains a fundamental philosophy that the human submitting the pull request is responsible for the code and its behavior, regardless of the tools used to create it. + +These tools can also generate a large volume of code changes, very rapidly. The above guidelines on PR quality still apply - large, undirected, or overly-scoped PR's are likely to be ignored, regardless of tooling used to generate them. + +### Violations + +We're thankful that we've rarely experienced major issues in our community. In all cases, the project leads shall have the final decision making authority when dealing with violations of these guidelines. + +## Yearly Development Cycle + +PhotonVision's Development Cycle follows the same general flow as the FRC Build Season. Larger experiments get done over the summer, fall focuses on testing and "production-readiness", build season focuses on keeping all teams running smoothly. + +The actual priorities also shift as developers have more or time to commit, or express interest in specific direction. + +PR's are absolutely always welcome. Just note depending on the scope and size, they may not be reviewed or merged immediately. + +## Project Governance + +This project is jointly lead by Matt and Banks, who may be contacted on Discord. They serve as a "Benevolent leader for life" role, coordinating and approving architecture as needed, and curating the team of developers who have Pull Request review and merge responsibilities. diff --git a/docs/source/docs/contributing/index.md b/docs/source/docs/contributing/index.md index 80b8487ef..12762ff26 100644 --- a/docs/source/docs/contributing/index.md +++ b/docs/source/docs/contributing/index.md @@ -1,6 +1,7 @@ # Contributing to PhotonVision Projects ```{toctree} +guidelines building-photon building-docs linting