This markdown file is meant to outline the conventions for workflow and processes for robot code. Conventions are important because they provide structure and consistency for the team. These rules are specific to Orbotics FRC Team 10152, but feel free to use or modify them for your own team as well!
We aim to make the robot software development process similar to a traditional software engineering process. During the FRC build season (6-7 weeks) and throughout the offseason, we will be coding in "sprints." Used in professional environments, code sprints are short time-boxed periods (typically one to four weeks), where there is a defined list of tasks to be completed. For Team 10152, we will be adjusting the length of sprints based on the stage of the season. For example, weekly sprints may be set during the build season due to time constraints, and monthly sprints during the offseason.
To facilitate sprints, we will be using Taiga, a free open-source project management tool. Since the Software Captain acts as a project manager, the Scrum template is most optimal. After kickoff weekend discussion, the Software Captain should create tickets in advance (preferably for the next 2 weeks) and assign them to the appropriate Directors and Specialists (roles specific to Team 10152).
To add a new ticket, navigate to Team Tree (by invite) and click on "Add New User Story." In industry, teams call new tasks "User Stories" because new features are added in the perspective of the end user. However, as FRC Robotics students we will refer to tasks as "tickets."
When you create a ticket, make sure to include a concise title, detailed description, and attachments if needed. Story points are a core part of software project management. Because we are working on robot code, ignore the UX, Design, and Frontend rows, and only add to the Backend row. In the workplace, 1 Story Point is equivalent to a day or half a day's work. Team 10152 will regard one story point as a day's work.
As a Software Captain, please use your best judgement when assigning story points to tickets. However, it won't always be perfect, and that's ok. There will be huge overestimations and underestimations, but you will develop an intuition throughout the year. Most importantly, encourage communication with your team to make sure everyone can manage their workload. FRC is supposed to be a great learning experience, but lots of fun at the same time!
Taiga allows users to configure the status of tickets. If you're working on a ticket, please set the status to In Progress. If your ticket is ready for review, please switch to Ready for Test. Once the ticket's corresponding PR has been reviewed and approved, the Software Captain will merge the PR and set the status to Done.
This markdown file is meant for outlining conventions. If you want to learn git, feel free to explore this document or the official GitHub documentation.
There will be two core branches: the main branch which consists of the final robot code for deployment during competitions, and the dev branch which will include all approved code. You may wonder, why do we distinguish between these two branches? This is mainly due to how sprints work. Approved code during a sprint will be merged into the dev branch, and all new code will be merged into the main branch at the end of the sprint.
However, as a developer, most of your interactions with the robot code repository will not be with those two branches, unless you're responsible for git actions, and will be working on separate branches. Each ticket has a corresponding number and name. When creating a new branch for your ticket, please refer to the convention of {your name}/{ticket-number}/{ticket-name}.
Having an orderly set of commit guidelines is crucial to any git workflow. This ensures organization and makes it easier to go through logs as the codebase becomes larger. For Team 10152, the core commit types are:
- Feats — use
Add,Update, orRemoveat the start of the message - Chore — routine maintenance tasks such as formatting or cleanup
- Fix — resolving a bug in the current code
The table below shows the expected formats for git commit messages:
| Type | Format | Example Commit Message |
|---|---|---|
| Feat | Add <description> |
Add drivetrain subsystem |
| Feat | Update <description> |
Update autonomous routine |
| Feat | Remove <description> |
Remove unused sensor logic |
| Chore | chore: <description> |
chore: formatting |
| Fix | fix: <description> |
fix: motor controller ID |
In a professional software environment, PR Review and Approval is just as important as coding. This is the process where other software engineers in your team review your submitted pull request and give feedback. Throughout the sprint, as a project manager, the Software Captain will bear most of the responsibility of review, and team members with time should partake as well. After a PR has enough approving reviews (2 for Team FRC 10152), it will be merged into the dev branch. Naturally, there are often more PRs waiting for review at the end of sprints, and it may be decided to allocate the final day just for getting these tickets in. We outline some rules to follow:
There are three core components when opening a PR:
- Title: Please enter in the following format: {Ticket Name}
[Ticket-{Number}] - Description: There are three sections that should be in every PR. The Description includes a brief summary of what the PR is for and a link to the Taiga ticket. The Solution includes how you solved the problem detailed in the Description. The Verification details what testing you did to make sure your code works the way it should (e.g. deploying it to the RoboRio and doing test runs).
- Right Column: This column allows you to add metadata for the PR. Assign yourself as a reviewer and add an appropriate label.
Here is an example of a PR to open:
To review PRs, navigate to the Pull Requests tab. For FRC Team 10152, our general guidelines for the individual reviewing process are the following:
- Check that code compiles and runs without errors
- Ensure changes match the ticket description
- Verify code follows team style conventions
- Confirm no unnecessary files or debug code are included
- Add comments if something is unclear or could be improved
- Approve only when the code is tested and meets requirements
When submitting a PR Review, the three types to keep in mind are:
- Approve: accept changes proposed in the PR to be merged
- Request Changes: submit feedback that should be addressed before the PR can be merged
- Comment: general feedback that isn't approval or a change request
PR Review is a core part of the software workflow. It increases organization and productivity while ensuring our robot code is clean. It is recommended that all software team members go through the experience of PR review throughout the season.