From e3900c4301c82933fdf295677bd7c0294ca5e08b Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Sat, 20 Jun 2026 13:49:27 -0400 Subject: [PATCH 01/12] Update contribution section and add CONTRIBUTING.md --- CONTIRBUTING.md | 7 ++++ src/config/sidebarConfig.ts | 1 + src/content/docs/contribution/index.mdx | 17 ++++++++ .../contribution/methodsOfContributing.mdx | 18 ++------- src/content/docs/contribution/roadmap.mdx | 4 +- src/content/docs/contribution/styleguide.mdx | 39 ++++++++----------- src/content/docs/index.mdx | 2 +- src/starlightOverrides/Header.astro | 2 +- 8 files changed, 49 insertions(+), 41 deletions(-) create mode 100644 CONTIRBUTING.md create mode 100644 src/content/docs/contribution/index.mdx diff --git a/CONTIRBUTING.md b/CONTIRBUTING.md new file mode 100644 index 0000000..e72c05d --- /dev/null +++ b/CONTIRBUTING.md @@ -0,0 +1,7 @@ +# Contributing + +Thank you for considering contributing to FRCSoftware.org! + +FRCSoftware.org is a community driven project, and we rely on the work of volunteer contributors to write and maintain articles. + +To learn more about contributing to the site and our styleguide, please visit our (contributing section)[https://frcsoftware.org/contribution/]. \ No newline at end of file diff --git a/src/config/sidebarConfig.ts b/src/config/sidebarConfig.ts index 9deb55d..ffd4097 100644 --- a/src/config/sidebarConfig.ts +++ b/src/config/sidebarConfig.ts @@ -44,6 +44,7 @@ export const sidebarSections: Record = { { label: 'Contribution', items: [ + { label: 'Contributing', slug: 'contribution'}, { label: 'Methods of Contributing', slug: 'contribution/methodsofcontributing' }, { label: 'Style Guide', slug: 'contribution/styleguide' }, { label: 'Contributors', slug: 'contribution/contributors' }, diff --git a/src/content/docs/contribution/index.mdx b/src/content/docs/contribution/index.mdx new file mode 100644 index 0000000..ee2acc1 --- /dev/null +++ b/src/content/docs/contribution/index.mdx @@ -0,0 +1,17 @@ +--- +title: Contributing +description: Contributing to FRCSoftware.org +--- + +Thank you for considering contributing to FRCSoftware.org! + +FRCSoftware.org is a community driven project, and we rely on the work of volunteer contributors to write and maintain articles. + +Currently, the project is in a very early stage, where the initial content for the website is being written. +This also includes significant discussion on the structure, philosophy, and roadmap of the website, which is all actively in development. +As such, this is a great time to get involved with the project. +The current focus is on getting stages 0, 1, and 2 complete and setting up the website and our processes for long-term success. + +This is a great time to get involved with this project and have an impact. + +Join our development Discord diff --git a/src/content/docs/contribution/methodsOfContributing.mdx b/src/content/docs/contribution/methodsOfContributing.mdx index 0d3b33d..93e8d6b 100644 --- a/src/content/docs/contribution/methodsOfContributing.mdx +++ b/src/content/docs/contribution/methodsOfContributing.mdx @@ -9,8 +9,6 @@ import Aside from '../../../components/Aside.astro'; ## Public Contribution -Anyone can create content for the website without markdown knowledge or GitHub, though it is preferred you learn how to use both to lessen the workload of other contributors. - 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: ``` @@ -24,10 +22,7 @@ This helps avoid duplicate work and keeps contribution priorities clear as the p 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, you may choose to either: - -1. Fork the repository on GitHub and submit pull requests for your work to be accepted (if you're more programming-savvy) -2. Work on an alternate platform such as Google Docs or Notion and let an internal contributor port it over to the website when you're done +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 @@ -46,6 +41,7 @@ Windows installers will almost always need to be the 64-bit version if there is - [VSCode](https://code.visualstudio.com/) - 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 - [GitHub Desktop](https://desktop.github.com/) (Optional - you can also use git interface in VSCode) - After installing, select "Sign in to GitHub.com" - Sign in or sign up for a new GitHub account, then click "Authorize Desktop" @@ -58,20 +54,12 @@ Windows installers will almost always need to be the 64-bit version if there is ### Steps to Start Writing Contributions -**For Public Contributors:** - 1. Go to the repository website 2. Click "Fork" near the top right, then click "Create Fork" on the next screen 3. Open GitHub Desktop and select "Clone a repository from the Internet..." or go to `file -> Clone repository...` in the very top left -4. Under "GitHub.com", select your forked `[username]/frcsoftware.github.io` repository and click "Clone" +4. Under "GitHub.com", select your forked `[username]/frcsoftware.org` repository and click "Clone" 5. After it clones the repository (downloads a copy of it to your computer), it will ask how you plan to use the fork. Select "To contribute to the parent project" and click "Continue" -**For Internal Contributors (added to the main repository):** - -1. Open GitHub Desktop and select "Clone a repository from the Internet..." or go to `file -> Clone repository...` in the very top left -2. Under "GitHub.com", select the main repository and click "Clone" -3. After it clones the repository (downloads a copy of it to your computer), it will ask how you plan to use the fork. Select "To contribute to the parent project" and click "Continue" - **How to Write and Pull Request Contributions** 1. Create a new branch by going to the "Current branch" dropdown at the top of GitHub Desktop, pressing "New branch", naming it and clicking "Create branch". diff --git a/src/content/docs/contribution/roadmap.mdx b/src/content/docs/contribution/roadmap.mdx index 74a8e21..f8a9e7a 100644 --- a/src/content/docs/contribution/roadmap.mdx +++ b/src/content/docs/contribution/roadmap.mdx @@ -6,4 +6,6 @@ next: false --- ## Roadmap -The roadmap is a work in progress, and can currently be found in `./plan.puml` in the repository. This page will be updated at a later date with the roadmap. \ No newline at end of file +The roadmap is a work in progress, and can be found on the GitHub project. + +Check out the GitHub project \ No newline at end of file diff --git a/src/content/docs/contribution/styleguide.mdx b/src/content/docs/contribution/styleguide.mdx index d6dbaab..c184850 100644 --- a/src/content/docs/contribution/styleguide.mdx +++ b/src/content/docs/contribution/styleguide.mdx @@ -17,27 +17,17 @@ This page will need to be updated as we go along with programming-based examples 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 billet chassis and ball drive, shouldn't be included to prevent confusion. - -On the other hand, including small details that you'd only discover through actually making the thing tends to be a lifesaver for everyone (such as electrical taping cat-tongue tape to make it not peel). +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. New products come out all the time, and equipping them with the skills lets students find creative solutions that no one would think of for their circumstances. +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 design mentors with experience. - -### To make this easier, here are a few tips: - -1. You can usually find extremes for each concept to make it more obvious. (stealth wheels vs brass flywheels for inertia.) - -2. It may be useful to find one or two meta team applications and figure out what fundamental trade offs are made for that decision. This helps learners understand how these concepts relate to each other. This also applies to mechanism examples. - -3. "how to cad xyz" and IRL nuances are very useful for certain applications. Examples include sketching linkages or tensioner placement depending on load. +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 @@ -46,18 +36,25 @@ 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 deadaxle pivots are better than liveaxle. But don't just say they're better, say: "Deadaxles have a higher second moment of area as the torque being directly transferred to the part. As a result your pivot is significantly more robust and less prone to breaking." - - Similarly, we know the Kraken motors are generally good. But explain why they are good, e.g. "We would recommend using Krakens on your drivetrain because they are extremely high torque motors and will improve your acceleration. In addition, they have integrated Talon FX motor controllers that make them easier to wire and feature a high resolution encoder which will help the precision of your swerve odometry. Keep in mind that Kraken motors are not yet compatible with stock REV Maxswerve modules and require an extra adaptor from WCP to mate with other existing modules." + - 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. + But, explain why this architecture is useful for FRC. - 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 and is unpopular; if it is popular it is worth explaining the disadvantages (See tank drive vs mecanum drive; explaining tank drive, as a relatively popular and simple drivetrain makes sense, but mecanum drive, a drivetrain that no longer makes sense in the era of swerve and has little-to-no pushing power or traction.) -- 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 +- 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 design trends are temporary and transient. +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 WCD and sheet metal superstructures was all the rage, but that doesn't mean that we should recommend them in this guide. Try your best to think about why something is popular, and what benefits in design, function, and execution they actually bring to the table. +- 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 @@ -83,8 +80,4 @@ You can use "you" when writing, when it makes writing less awkward. However, try ### Links: - External links should generally open in a new tab -- Links to CAD documents should use the LinkButton component: - ```mdx - CAD Link - ``` - Internal links should use relative paths: `[Link Text](/path/to/page)` diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 775c380..24c902f 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -37,7 +37,7 @@ import HomeCard from '../../components/HomeCard.astro'; /> diff --git a/src/starlightOverrides/Header.astro b/src/starlightOverrides/Header.astro index e9f54b2..1ebbcdc 100644 --- a/src/starlightOverrides/Header.astro +++ b/src/starlightOverrides/Header.astro @@ -18,7 +18,7 @@ const navLinks = [ // { href: "/mechanism-examples/", label: "Mechanism Examples" }, // { href: "/best-practices/", label: "Best Practices" }, // { href: "/resources/", label: "Other Resources" }, - { href: "/contribution/methodsofcontributing/", label: "Contribution" }, + { href: "/contribution/", label: "Contribution" }, ]; const currentPath = Astro.url.pathname; From 1b12ff4715b3781afd68c8b1f80a8c1495d83fc1 Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Sat, 20 Jun 2026 13:50:24 -0400 Subject: [PATCH 02/12] Remove plan.puml Outdated --- plan.puml | 79 ------------------------------------------------------- 1 file changed, 79 deletions(-) delete mode 100644 plan.puml diff --git a/plan.puml b/plan.puml deleted file mode 100644 index cf1ec11..0000000 --- a/plan.puml +++ /dev/null @@ -1,79 +0,0 @@ -@startmindmap -* Home page -** Getting started -*** Download git -*** Download WPILib VS Code -** Java/git -*** Module 0: Repo setup -**** Fork starter repo -**** Clone locally -**** Configure name/email -**** Run tests or app -**** Exercise: verify build output -**** Git: git status, git log --oneline -*** Module 1: Variables + commits -**** Java: variables, types, input/output -**** Exercise: implement score tracker -***** Add Score class -***** Print running total -**** Git: stage + commit -***** git add -***** git commit -m "Add score tracker" -*** Module 2: Conditionals + branches -**** Java: if/else, boolean logic -**** Exercise: decision helper -***** Add isReadyToScore() -***** Add unit test -**** Git: branch workflow -***** git switch -c feature/decision -***** git push -u origin feature/decision -***** git switch main -***** git pull -*** Module 3: Loops + merge -**** Java: for/while, collections intro -**** Exercise: process match log -***** Parse list of events -***** Count scoring cycles -**** Git: merge or rebase -***** git merge feature/decision -***** Resolve conflicts -*** Module 4: Debugging + bisect -**** Java: breakpoints, step over/into -**** Exercise: fix a regression -***** Failing test added in repo -***** Identify bad commit -**** Git: bisect -***** git bisect start -***** git bisect bad -***** git bisect good -***** git bisect reset -*** Module 5: Remote sync -**** Git: push, pull, fetch -**** Exercise: sync upstream -***** Add upstream remote -***** git fetch upstream -***** git merge upstream/main -** Command Based -*** What is a command -*** What is a subsystem -*** What is: robot, robotcontainer, constants -*** Motor -**** REVLib -**** Phoenix -*** Programming 2025 Kitbot -**** Programming Drive Train -***** Setting up 4 "motors" -***** Setting up the configs -***** Making the Inline command -**** Programming Coral Mech -***** Setting up a "motor" -***** Setting up the config -***** Making Inline Commands -***** Button binding -****** Drive -****** Score -** Debugging FRC Code -** linting/CI -** debugging -** PID (intro) -@endmindmap From 2f98c6a7942486d1f9e9bb2231e81e34605a9a52 Mon Sep 17 00:00:00 2001 From: Andrew Haselton <13470989+roboteer5291@users.noreply.github.com> Date: Sat, 20 Jun 2026 16:39:24 -0400 Subject: [PATCH 03/12] Update src/content/docs/contribution/methodsOfContributing.mdx Co-authored-by: Adriana --- src/content/docs/contribution/methodsOfContributing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/contribution/methodsOfContributing.mdx b/src/content/docs/contribution/methodsOfContributing.mdx index 93e8d6b..8f036b8 100644 --- a/src/content/docs/contribution/methodsOfContributing.mdx +++ b/src/content/docs/contribution/methodsOfContributing.mdx @@ -77,7 +77,7 @@ Windows installers will almost always need to be the 64-bit version if there is All the website files and folders are contained in the `src/content/docs` folder. -6. Whenever you reach a good point to stop where you want to save your changes to the cloud, you want to make what's called a "commit", which is where the changes are saved to the branch. You then have to "push" any commits to get them uploaded to the cloud, otherwise they will remain local. You can do this through VS Code or GitHub Desktop, but we'll go through GitHub Desktop to keep all version control actions centralized there. +Whenever you reach a good point to stop where you want to save your changes to the cloud, you'll make a “commit”. You then have to “push” any commits to get them uploaded to the cloud. 7. Open GitHub Desktop and make sure "Changes" on the sidebar is selected. All changes selected in the sidebar will be added to the commit (the changes are "staged" for the commit). Type a summary of the commit (description optional) and press "Commit to [branch]". 8. Click the button to push the commit(s) you've made to the cloud (either up above or in the middle of the screen). From 0c2616418bb509e10bba52e8dd6607f2fe3ed46d Mon Sep 17 00:00:00 2001 From: Andrew Haselton <13470989+roboteer5291@users.noreply.github.com> Date: Sat, 20 Jun 2026 16:40:01 -0400 Subject: [PATCH 04/12] Update src/content/docs/contribution/methodsOfContributing.mdx Co-authored-by: Adriana --- src/content/docs/contribution/methodsOfContributing.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/contribution/methodsOfContributing.mdx b/src/content/docs/contribution/methodsOfContributing.mdx index 8f036b8..d99a9ce 100644 --- a/src/content/docs/contribution/methodsOfContributing.mdx +++ b/src/content/docs/contribution/methodsOfContributing.mdx @@ -65,7 +65,9 @@ Windows installers will almost always need to be the 64-bit version if there is 1. Create a new branch by going to the "Current branch" dropdown at the top of GitHub Desktop, pressing "New branch", naming it and clicking "Create branch". - Typically you want to make changes in branches (not main), then do what's called a "pull request" to get those changes "pulled" and merged over to the original main branch - Name the branch something related to the overall changes you're making, e.g. "contributors-guide" or "3A-cleanup". You should expect to delete the branch after a pull request, so keep it specific enough to your changes - - Make sure to publish the branch by clicking the button for it that shows up after you create a new branch +1. Create a new branch. You want to make changes on your branch then do a "pull request" to get those changes "pulled" and merged over to the original main branch +- Name the branch something related to the overall changes you're making, e.g. "contributors-guide" or "1A-cleanup". You should expect to delete the branch after a pull request, so keep it specific enough to your changes +- 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. Set up VS Code how you like if this is your first time running it (themes, extensions). From b925ae024af013fe33ba7fdaac68d84c94cc3a46 Mon Sep 17 00:00:00 2001 From: Andrew Haselton <13470989+roboteer5291@users.noreply.github.com> Date: Sat, 20 Jun 2026 16:40:19 -0400 Subject: [PATCH 05/12] Update src/content/docs/contribution/methodsOfContributing.mdx Co-authored-by: Adriana --- src/content/docs/contribution/methodsOfContributing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/contribution/methodsOfContributing.mdx b/src/content/docs/contribution/methodsOfContributing.mdx index d99a9ce..e961f7f 100644 --- a/src/content/docs/contribution/methodsOfContributing.mdx +++ b/src/content/docs/contribution/methodsOfContributing.mdx @@ -80,7 +80,7 @@ All the website files and folders are contained in the `src/content/docs` folder Whenever you reach a good point to stop where you want to save your changes to the cloud, you'll make a “commit”. You then have to “push” any commits to get them uploaded to the cloud. -7. Open GitHub Desktop and make sure "Changes" on the sidebar is selected. All changes selected in the sidebar will be added to the commit (the changes are "staged" for the commit). Type a summary of the commit (description optional) and press "Commit to [branch]". + 7. When ready to commit to a branch, type a summary of the commit (if using Github Desktop, a description is optional) and commit your branch. 8. Click the button to push the commit(s) you've made to the cloud (either up above or in the middle of the screen). -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. +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. diff --git a/src/content/docs/contribution/styleguide.mdx b/src/content/docs/contribution/styleguide.mdx index 601b26c..829e95d 100644 --- a/src/content/docs/contribution/styleguide.mdx +++ b/src/content/docs/contribution/styleguide.mdx @@ -45,8 +45,8 @@ Don't deal in absolutes. - 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." + 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**.