GitHub Usage

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.

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:

name: Task
body:
  - type: textarea
    id: description
    attributes:
      label: Description
      description: Specific task (e.g., Tune PID gains for intake).
    validations:
      required: true
  - type: input
    id: deadline
    attributes:
      label: Deadline
      description: Date that this task should be completed by.
  - type: textarea
    id: related_links
    attributes:
      label: Related Links
      description: Links to relevant code files, PRs, or docs.

See 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 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
• A checklist to verify code standards and successful builds

Here’s an example pull request template:

## Description

Describe the changes made in this PR.
- List the key changes, files modified, or features added
- Be specific about what was implemented

## Why These Changes?

Explain the reasoning behind these changes:
- What problem does this solve?
- Why was this approach chosen?

## Testing

How have you tested these changes?
- Unit tests added
- Tested on robot or simulation

## Related Issues

Link to any related issues or PRs:
- Closes #issue_number
- Related to #issue_number

## Checklist

- [ ] Code follows project coding standards
- [ ] No linting errors
- [ ] Code builds successfully (`./gradlew build`)
- [ ] Tests pass (`./gradlew test`)

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.

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.