Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .prettierrc
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"singleQuote": true,
"trailingComma": "all",
"tabWidth": 4,
"plugins": ["prettier-plugin-astro", "prettier-plugin-sentences-per-line"],
"plugins": ["prettier-plugin-astro"],
"overrides": [
{
"files": "*.astro",
Expand All @@ -14,7 +14,8 @@
{
"files": "*.mdx",
"options": {
"proseWrap": "preserve"
"printWidth": 120,
"proseWrap": "always"
}
}
]
Expand Down
1 change: 0 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,6 @@
"mdx2vast": "^0.3.1",
"prettier": "^3.8.4",
"prettier-plugin-astro": "^0.14.1",
"prettier-plugin-sentences-per-line": "^0.2.3",
"remark-cli": "^12.0.1",
"remark-frontmatter": "^5.0.0",
"remark-gfm": "^4.0.1",
Expand Down
19 changes: 0 additions & 19 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 18 additions & 12 deletions src/content/docs/best-practices/ci-checks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,11 @@ codeRegionSources:
format: best-practices/ci-checks/format.yml
---

Continuous Integration (CI) is a software development practice where developers frequently merge code changes into a shared repository, triggering automated builds and tests to ensures the codebase remains stable.
CI checks are automated tests that run when code is pushed or a pull request is opened.
They help ensure that your code builds, meets programming standards, and is formatted correctly before merging.
You can create CI checks using [GitHub Actions](https://docs.github.com/en/actions/get-started/continuous-integration).
Continuous Integration (CI) is a software development practice where developers frequently merge code changes into a
shared repository, triggering automated builds and tests to ensures the codebase remains stable. CI checks are automated
tests that run when code is pushed or a pull request is opened. They help ensure that your code builds, meets
programming standards, and is formatted correctly before merging. You can create CI checks using
[GitHub Actions](https://docs.github.com/en/actions/get-started/continuous-integration).

<Aside type="note">
CI checks can only check for certain attributes of the code and cannot ensure that the code is functional or well-written.
Expand All @@ -21,34 +22,39 @@ CI checks do not replace pull request reviews.

## Build

To verify that your robot code builds, create a GitHub Actions workflow file `.github/workflows/build.yml` with the following code:
To verify that your robot code builds, create a GitHub Actions workflow file `.github/workflows/build.yml` with the
following code:

```yaml {build}

```

## Code Quality

Static analysis is the process of analyzing code without executing it.
Static analysis tools help catch bugs, maintain programming standards, and improve code quality.
Using static analysis tools is considered a good practice because they offer automated ways of flagging bad programming practices such as unused code.
Static analysis is the process of analyzing code without executing it. Static analysis tools help catch bugs, maintain
programming standards, and improve code quality. Using static analysis tools is considered a good practice because they
offer automated ways of flagging bad programming practices such as unused code.

To configure, add the [PMD](https://docs.gradle.org/current/userguide/pmd_plugin.html) and [Spotbugs](https://plugins.gradle.org/plugin/com.github.spotbugs) plugin in the `plugins {}` block of your `build.gradle` file.
To configure, add the [PMD](https://docs.gradle.org/current/userguide/pmd_plugin.html) and
[Spotbugs](https://plugins.gradle.org/plugin/com.github.spotbugs) plugin in the `plugins {}` block of your
`build.gradle` file.

```groovy {staticAnalysis}

```

To run code quality checks, create a GitHub Actions workflow file `.github/workflows/code-quality.yml` with the following code:
To run code quality checks, create a GitHub Actions workflow file `.github/workflows/code-quality.yml` with the
following code:

```yaml {codeQuality}

```

## Code Formatting

[Spotless](https://github.com/diffplug/spotless) can also be run as a CI check to verify that code is formatted correctly.
To add a code formatting CI check, create a GitHub Actions workflow file `.github/workflows/format.yml` with the following code:
[Spotless](https://github.com/diffplug/spotless) can also be run as a CI check to verify that code is formatted
correctly. To add a code formatting CI check, create a GitHub Actions workflow file `.github/workflows/format.yml` with
the following code:

```yaml {format}

Expand Down
5 changes: 3 additions & 2 deletions src/content/docs/best-practices/code-formatter.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ description: Best practices for using a code formatter
---

Code formatters help ensure that the style of code written is consistent throughout the entire codebase.
[Spotless](https://github.com/diffplug/spotless) is a Gradle plugin that can automatically format code with configurable options.
Steps for configuring Spotless are provided in the [Using a Code Formatter WPILib docs](https://docs.wpilib.org/en/stable/docs/software/advanced-gradlerio/code-formatting.html).
[Spotless](https://github.com/diffplug/spotless) is a Gradle plugin that can automatically format code with configurable
options. Steps for configuring Spotless are provided in the
[Using a Code Formatter WPILib docs](https://docs.wpilib.org/en/stable/docs/software/advanced-gradlerio/code-formatting.html).

## Spotless Gradle Commands

Expand Down
62 changes: 34 additions & 28 deletions src/content/docs/best-practices/git-usage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@ description: Best practices for Git

## Commits

A commit is a saved state of your repository.
You should make a commit every time you complete a task (e.g. `Add per-path auto choosers`, `Fix joystick inputs inversion`, `Tune chassis heading PID gains`).
This helps keep track of when new code is added.
When you add changes through smaller, focused commits, you can isolate when a bug is introduced and easily roll back to a working state
Writing descriptive commit messages make it easy to see exactly what changed.
While diffs can only show what changed in code, commit messages can also communicate the context about a change and explain the why.
By convention, commit messages are concise, begin with a capital letter, don't use punctuation, and are in the imperative mood.
A commit is a saved state of your repository. You should make a commit every time you complete a task (e.g.
`Add per-path auto choosers`, `Fix joystick inputs inversion`, `Tune chassis heading PID gains`). This helps keep track
of when new code is added. When you add changes through smaller, focused commits, you can isolate when a bug is
introduced and easily roll back to a working state Writing descriptive commit messages make it easy to see exactly what
changed. While diffs can only show what changed in code, commit messages can also communicate the context about a change
and explain the why. By convention, commit messages are concise, begin with a capital letter, don't use punctuation, and
are in the imperative mood.

Compare the following examples of good vs bad commit messages:

Expand All @@ -21,51 +21,57 @@ Compare the following examples of good vs bad commit messages:
| Use the imperative mood: "Refactor swerve drive logic" | Are past tense, lowercase, or punctuated: "refactored swerve drive logic." |
| Specific and provide context: "Fix swerve drive limiter bug for reliable drive control" | Are vague: "Fix bug" or "WIP" |

See this specification on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to learn about standardized conventions for writing commit messages.
See this specification on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to learn about
standardized conventions for writing commit messages.

<Aside type="tip">
Commit early and commit often.

</Aside>

For advanced users, the command line offers more capabilities.
[GitHub Desktop](https://docs.github.com/en/desktop/managing-commits) presents a simpler way to manage commits, using checkboxes to select files to commit, a text box for commit messages, and a button to create a commit.
[GitHub Desktop](https://docs.github.com/en/desktop/managing-commits) presents a simpler way to manage commits, using
checkboxes to select files to commit, a text box for commit messages, and a button to create a commit.

## Branches

The `main` branch is where the working, tested version of the code lives during the build season.
When multiple programmers are working on different changes, creating separate development branches can help prevent merge conflicts.
The `main` branch is where the working, tested version of the code lives during the build season. When multiple
programmers are working on different changes, creating separate development branches can help prevent merge conflicts.
For example, creating a seprate branch for vision code ensures that the code on the drivetrain branch isn't affected.
Making branches for each competition helps isolate fixes and ensures that code is still reviewed before merging to `main`.
Making branches for each competition helps isolate fixes and ensures that code is still reviewed before merging to
`main`.

To maintain a branch, you must stay up to date with `main`.
A merge and a rebase are both ways of integrating changes from one branch into another, but they do it differently.
A merge combines branches by creating a new merge commit that connects their histories.
This is useful for shared branches where multiple developers are contributing simultaneously or merging a branch into `main`.
A rebase rewrites the history of your branch sequentially and results in a clean, linear history.
This is useful for a branch that only exists locally.
Never rebase commits that have already been pushed to the remote repository, as this results in diverged commit histories.
To maintain a branch, you must stay up to date with `main`. A merge and a rebase are both ways of integrating changes
from one branch into another, but they do it differently. A merge combines branches by creating a new merge commit that
connects their histories. This is useful for shared branches where multiple developers are contributing simultaneously
or merging a branch into `main`. A rebase rewrites the history of your branch sequentially and results in a clean,
linear history. This is useful for a branch that only exists locally. Never rebase commits that have already been pushed
to the remote repository, as this results in diverged commit histories.

- To merge: `git fetch` then `git merge origin/main`
- To rebase: `git fetch` then `git rebase origin/main`

It is a good practice to push to your branch frequently to back up your work in the remote repository and make it visible to other programmers using `git push.`
It is a good practice to push to your branch frequently to back up your work in the remote repository and make it
visible to other programmers using `git push.`

## Repositories

Creating a new repository for different major projects or new seasons is a helpful way to keep track of projects.
Repositories should have names that represent the purpose of its code, like "2026-rebuilt", "2026-kitbot", and "2026-offseason-turret".
Repositories should have names that represent the purpose of its code, like "2026-rebuilt", "2026-kitbot", and
"2026-offseason-turret".

## Additional Information

An in-depth tutorial can be found at the official [git website](https://git-scm.com/docs/gittutorial).

A guide for correcting common mistakes can be found at the [git flight rules repository](https://github.com/k88hudson/git-flight-rules/blob/master/README.md).
A guide for correcting common mistakes can be found at the
[git flight rules repository](https://github.com/k88hudson/git-flight-rules/blob/master/README.md).

[GitHub Desktop](https://docs.github.com/en/desktop) is an alternative to command line or web browser interactions with GitHub.
With GitHub Desktop, you can perform Git commands through a graphical user interface.
It's a good resource for teams who are new to programming and may not have a lot of Git support or experience on the team, especially rookie teams.
While GitHub Desktop offers it's own simplified ways of using Git and GitHub, the information mentioned in this section can still apply.
[GitHub Desktop](https://docs.github.com/en/desktop) is an alternative to command line or web browser interactions with
GitHub. With GitHub Desktop, you can perform Git commands through a graphical user interface. It's a good resource for
teams who are new to programming and may not have a lot of Git support or experience on the team, especially rookie
teams. While GitHub Desktop offers it's own simplified ways of using Git and GitHub, the information mentioned in this
section can still apply.

[Source control in VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview) also offers a GUI for integrated source code management.
It lets you run Git commands from the command palette.
[Source control in VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview) also offers a GUI for integrated
source code management. It lets you run Git commands from the command palette.
48 changes: 26 additions & 22 deletions src/content/docs/best-practices/github-usage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,31 +8,35 @@ codeRegionSources:

## Issues

An issue is a way of planning tasks and tracking bugs.
You can create issues in your repository to plan, discuss, and share tasks.
When opening an issue, you should add a title and description to clearly summarize the task.
The Assignees feature is helpful for delegating tasks to programmers within your team.
The Milestones feature can be used to group issues with specific deadlines and track progress.
An issue is a way of planning tasks and tracking bugs. You can create issues in your repository to plan, discuss, and
share tasks. When opening an issue, you should add a title and description to clearly summarize the task. The Assignees
feature is helpful for delegating tasks to programmers within your team. The Milestones feature can be used to group
issues with specific deadlines and track progress.

Issue templates are helpful for providing guidance for opening issues and encourage students to specify the content of their issue.
To create issue templates, create a `.github/ISSUE_TEMPLATE` folder and add Markdown files for different types of issues.
Issue templates are helpful for providing guidance for opening issues and encourage students to specify the content of
their issue. To create issue templates, create a `.github/ISSUE_TEMPLATE` folder and add Markdown files for different
types of issues.

Here's an example issue template:

```markdown {task}

```

See [Configuring issue templates for your repository](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) for a more in-depth guide to using issue templates.
See
[Configuring issue templates for your repository](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
for a more in-depth guide to using issue templates.

## Pull Requests

Pull requests are proposals to merge changes on a separate branch into the `main` branch of a repository, providing a space for comments and suggestions to be made and implemented and ensuring that any code that goes on the robot is reviewed beforehand.
Pull requests help programmers review changes before merging them, catch bugs early, and maintain code quality.
Pull requests are proposals to merge changes on a separate branch into the `main` branch of a repository, providing a
space for comments and suggestions to be made and implemented and ensuring that any code that goes on the robot is
reviewed beforehand. Pull requests help programmers review changes before merging them, catch bugs early, and maintain
code quality.

Pull request templates encourage students to provide context for their changes and offer checklists to enforce programming standards.
To create a template, create a `.github/pull_request_template.md` file.
The template could ask to include:
Pull request templates encourage students to provide context for their changes and offer checklists to enforce
programming standards. To create a template, create a `.github/pull_request_template.md` file. The template could ask to
include:

- A description of changes made
- A link to any issues this pull request closes
Expand All @@ -44,16 +48,16 @@ Here's an example pull request template:

```

To review a pull request, read the pull request title and description, verify that all CI checks passed, and open the **Files changed** tab to view the diff.
You can comment on specific lines and suggest changes.
To review a pull request, read the pull request title and description, verify that all CI checks passed, and open the
**Files changed** tab to view the diff. You can comment on specific lines and suggest changes.

Squash and merge is a clean way of merging a branch into `main`.
It combines multiple commits on a branch into a single one rather than adding them individually to `main` and cluttering version history.
Squash and merge is a clean way of merging a branch into `main`. It combines multiple commits on a branch into a single
one rather than adding them individually to `main` and cluttering version history.

## GitHub Projects

GitHub Projects are a tool for project management that integrates with your issues and pull requests.
You can create customized tables, boards, and roadmaps to plan, track, and visualize changes and their metadata.
With Projects, issues can be ranked by priority and organized by completion status.
You can use automation with pre-built workflow to update your Projects automatically.
Read more about Projects in the [About Projects GitHub docs](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects).
GitHub Projects are a tool for project management that integrates with your issues and pull requests. You can create
customized tables, boards, and roadmaps to plan, track, and visualize changes and their metadata. With Projects, issues
can be ranked by priority and organized by completion status. You can use automation with pre-built workflow to update
your Projects automatically. Read more about Projects in the
[About Projects GitHub docs](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects).
Loading