Methods of Contributing

Public Contribution

FRCSoftware.org is just getting started, so the easiest way to propose work is by opening a GitHub issue in the main repository. Use this template in your issue:

Issue/content:
Solution or Notes about the execution of the content:
When do you plan on finishing?:

This helps avoid duplicate work and keeps contribution priorities clear as the project grows.

If you’re given approval to start working on it, continue discussion in the issue thread so everyone can follow progress.

When you start on your work, fork the repository on GitHub and submit pull requests for your work to be accepted.

Setting up GitHub and VS Code For Contributing

Install Prerequisites

Make sure to download the correct versions for the OS that you have (Windows, Mac, or Linux).

Windows installers will almost always need to be the 64-bit version if there is a distinction.

• The latest version of Git
  • Follow instructions for your OS
  • Use all default options for installation
• Node.js LTS
  • Download the LTS version for your OS
  • Use all default options for installation
• pnpm
• VSCode
  • Download the stable build for your OS
  • Use all default options for installation, except creating a desktop icon if you want
  • A WPILib VSCode installation will work perfectly fine
  • Recommended: Install a spellcheck extension to catch mistakes early

Steps to Start Writing Contributions

1. Go to the repository website
2. Click “Fork” near the top right, then click “Create Fork” on the next screen
3. Clone your fork of the repository to your computer

How to Write and Pull Request Contributions

1. Work on your changes in a new branch in your fork of the repository. This allows you to have multiple versions of the repository at once, for example if you are working on two separate tasks
   • Make sure to publish the branch
2. Click “Open in Visual Studio Code” to open VS Code.
3. If you get a pop-up that says “Do you trust the authors of the files in this folder?”, check the box next to “Trust the authors of all files in the parent folder ‘GitHub’” (for no further popups when you clone repositories in the future) and click “Yes, I trust the authors”.
4. Make your changes
5. Run the formatter and linter before committing
   • Use pnpm format to run the formatter
   • Use pnpm lint to run all lint steps
   • The formatter will apply code formatting to the docs section of the side, to maintain a consistent style
   • The linter steps will perform various checks in the code to ensure basic functionality
6. Make and commit your changes

Tip

All the website files and folders are contained in the src/content/docs folder.

In GitHub on your fork of the repository, use the “sync” button to easily rebase your branch onto the primary frcsoftware.org repository to keep up to date with any changes that have been made since you started your branch

Tip

Make sure to update your branch from main frequently! If you don’t, you may have to resolve big conflicts between your changes and changes someone else made to main.

5. Once you’ve completed your changes, check that you’ve committed everything, that your branch is up to date with main, and that everything has been pushed. Then, create a pull request on GitHub, from your branch to the main branch of the frcsoftware.org repository.

To recap the contribution steps, do the combination of creating and publishing a branch, making changes and commits, updating from main, pushing commits, and creating a pull request.

How to Get The Local Preview of the Website Running

You can get a local hosted version of the website to have a live preview of the site while editing.

1. Open the repository in VS Code (doesn’t matter which branch)
2. Toggle the bottom panel on if there isn’t one with the shortcut Ctrl + J
3. Click the dropdown next to the + on the top righthand side of the bottom panel and click “Terminal”
4. Run the command pnpm install to install all needed packages (FIRST TIME)
5. Run the command pnpm dev to start the development server
6. If everything went smoothly it should say its serving on something like http://localhost:4321

Make sure to run pnpm dev every time you open VS Code to edit.

Tip

After clicking on the terminal in the bottom panel, you can use Ctrl + C to terminate the local website hosting.

Note

When you switch branches using GitHub Desktop, the local preview will follow without any problems.