Contribution Style Guide

Note

FRCSoftware.org is just getting started, and has taken a lot from FRCDesign.org

This page will need to be updated as we go along with programming-based examples, and parts may need to be rewriten due to the differences in programming and design.

Futureproofing and Usefulness

To make the content you write useful for teams of all resource levels, while maintaining validity in the future, the goal isn’t to go broad and shallow, but rather to go extra deep so you can equip students with the understanding of the underlying fundamentals behind concepts which they can then apply to their own unique situations. Pros and cons are context dependent while fundamentals are universal.

At the same time, things that aren’t easily accessible and/or commonly used by teams, like state-space control or MPC, shouldn’t be included to prevent confusion.

Why is this important?

1. We don’t need to figure out the pros and cons of everything for students to make a decision. Software is a space that can change very quickly, and equipping them with the skills to make a decision is more important than using a specific technique.

2. This enables students to understand WHY a team would make a certain decision and figure out tradeoffs without us explicitly telling them.

3. It makes it significantly less intensive to future proof and maintain. If the meta shifts, having to redo sections to stay competitive is time consuming. If the project dies and is no longer maintained, the information stays useful for way longer.

4. The small details are often the experience gap between the most reliable successful robots and not. It’s a lifesaver for teams without experience, and reduces the review workload on software mentors with experience.

Inspired by gm0’s Style Guide

Don’t deal in absolutes.

• Only a Sith deals in absolutes
• Use pros/cons lists to compare options
• Explain WHY something is good or bad
  • For example, we all know that splitting code into multiple files (but not too many) is better than one giant file. But don’t just say that it’s better, say “Breaking up your code into separate files makes it easier to read and isolates independent sections of the robot code from one another, making it easier to maintain.”
  • Similarly, this course uses a command-based architecture because its authors believe that it’s generally the best option for teams. However, many teams are successful with different structures, such as ones based around non-command state machines, ROS setups, or even just a smart application of if statements and logic inside a periodic function. Instead of saying “Use commands because they make it easier to program your robot,” say that “The commands library is a good choice for programming your robot as it ensures that no two actions can conflict with each other by only allowing each mechanism to be used by one action/command at a time, while also providing a strong framework to build autonomous sequences and integrate automation.”
• Still emphasize that teams are free to explore and innovate, but help set realistic expectations (see the following point)

FRCSoftware.org is a guide from a competitive standpoint.

• Try to leave out stuff that doesn’t work well or is too complex compared to the rest of this course. For example, MPC or state space control can work very well, but requires a significant amount of controls and math knowledge that is far beyond what the rest of this course requires
• Try to leave opinions out as much as possible. Do not speak authoritatively on stuff you do not have first-hand experience with whenever possible

Keep in mind that FRC software trends are temporary and transient.

• Just because something is popular one season doesn’t mean it’s the end all be all. There was a time when commands v1 was the most powerful framework available, but now we’re on commands v3. Currently, there are many teams using a RobotState.java file but there are also many not using it. Think about why this could have such a split and how the changing and evolving frameworks, like commands v3, address this.

Standards

File Formats:

• Compress images to .webp format using squoosh
• Embed longer videos using the YouTube component, and shorter videos with a webm file
• Add images using markdown syntax: ![Alt text](/path/to/image.webp)

Brand Standards

Adhere to brand standards when possible.

• Abide by FIRST Trademark guidelines, available here
• The first instance of FIRST and FRC on a page should include the registered trademark symbol (i.e, FIRST)
• Always capitalize and italicize the name FIRST
• Do NOT use a possessive on the FIRST name (e.g, FIRST’s)
• This also applies to team names: spell them how they are officially spelled
• Check The Blue Alliance if you don’t know how to spell a team’s name

You can use “you” when writing, when it makes writing less awkward. However, try avoiding excessively using it.

Links:

• External links should generally open in a new tab
• Internal links should use relative paths: [Link Text](/path/to/page)

Linting and Formatting

All content must pass the project’s linting and formatting checks before merging.

Sentence-per-line

Every sentence in .mdx and .md files must be on its own line. This ensures cleaner diffs and easier review. Enforced by prettier-plugin-sentences-per-line.

Running the checks

Command	Action
pnpm lint	ESLint for .ts, .mjs, .astro files
pnpm lint:md	Remark-lint for .mdx files
pnpm format:check	Prettier check — all file types (includes sentence-per-line)
pnpm typecheck	astro check for TypeScript errors
pnpm prettier --write	Auto-fix all formatting and sentence-per-line issues

Run all checks locally before pushing:

pnpm lint && pnpm lint:md && pnpm format:check && pnpm typecheck

If pnpm format:check fails, run pnpm prettier --write . to auto-fix.