diff --git a/CONTIRBUTING.md b/CONTIRBUTING.md new file mode 100644 index 0000000..e7b9975 --- /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/]. diff --git a/README.md b/README.md index fe70dea..85dcec8 100644 --- a/README.md +++ b/README.md @@ -368,6 +368,9 @@ pnpm --version # Should be 10.x or higher | `pnpm dev` | Start local dev server at `localhost:4321` | | `pnpm build` | Build production site to `./dist/` | | `pnpm preview` | Preview build locally before deploying | +| `pnpm format` | Run the formatter | +| `pnpm lint` | Run the linter for Javascript files | +| `pnpm lint:md` | Run the linter for Markdown files | ## Deployment @@ -380,9 +383,9 @@ To deploy: ## Contributing -See the [Contribution Guide](/contribution/methodsofcontributing/) on the website for details on how to contribute to FRCSoftware.org. +See the [Contribution Guide](https://frcsoftware.org/contribution/) on the website for details on how to contribute to FRCSoftware.org. ## Links - [FRCSoftware.org](https://frcsoftware.org/) -- [GitHub Repository](https://github.com/frcsoftware/frcsoftware.github.io) +- [GitHub Repository](https://github.com/frcsoftware/frcsoftware.org) 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 diff --git a/src/content/docs/contribution/index.mdx b/src/content/docs/contribution/index.mdx new file mode 100644 index 0000000..ebe2acb --- /dev/null +++ b/src/content/docs/contribution/index.mdx @@ -0,0 +1,19 @@ +--- +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 still 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 4f3ed5c..7f51871 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: @@ -18,17 +16,13 @@ Use this template in your issue: Issue/content: Solution or Notes about the execution of the content: When do you plan on finishing?: -Using an alternate platform or forking on Github?: ``` 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, 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 @@ -44,83 +38,49 @@ Windows installers will almost always need to be the 64-bit version if there is - [Node.js LTS](https://nodejs.org/) - Download the LTS version for your OS - Use all default options for installation +- [pnpm](https://pnpm.io/installation) - [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 -- [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" - - If you choose to sign up, you must verify your account with a captcha at the end of the registration and an emailed code - - If the captcha fails, try disabling a privacy extension that might be interfering - - Set up the rest of your account (you may choose to sign up for GitHub education but that isn't required, the free version is fine) - - If it doesn't take you to the authorization page after signing up, go back to the GitHub Desktop application, press "Cancel", then select "Sign in to GitHub.com" again - - Allow your browser to open GitHub Desktop - - Click "Finish" + - A WPILib VSCode installation will work perfectly fine + - Recommended: Install a spellcheck extension to catch mistakes early ### 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" -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" +3. Clone your fork of the repository to your computer **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". - - 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. 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. Set up VS Code how you like if this is your first time running it (themes, extensions). - - The "Code Spell Checker" extension is suggested - - Enable autosave in the `file` menu by toggling it on -5. Make a set of changes. +4. Make your changes +5. Run the formatter and linter before committing + - Use `pnpm format` to run the formatter + - Use `pnpm lint` followed by `pnpm lint:md` to run the linter 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 -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. -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). +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 - -9. To keep your code up to date with the original repository's main branch, open the "branch" menu at the top of the screen and click "Update from main". - If some commits get pulled to your branch from main, you can push to update your branch in the cloud again. - - -10. Once you're satisfied enough with your set of changes to request to add them to the main website, and have committed all changes, checked for updates, and pushed all commits, create a pull request through the menu in the middle of GitHub Desktop. - This will bring you to the website where you can describe the changes you made and want to pull to the website and assign an issue that it will fix. - One of the internal contributors will review your pull request after you submit it and will either approve it and merge it with the main branch or make comments about things that need fixed before it can get merged. +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/roadmap.mdx b/src/content/docs/contribution/roadmap.mdx index 09fd6b2..2ae5165 100644 --- a/src/content/docs/contribution/roadmap.mdx +++ b/src/content/docs/contribution/roadmap.mdx @@ -7,5 +7,8 @@ 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. +The roadmap is a work in progress, and can be found on the GitHub project. + + + Check out the GitHub project + diff --git a/src/content/docs/contribution/styleguide.mdx b/src/content/docs/contribution/styleguide.mdx index 4d16207..829e95d 100644 --- a/src/content/docs/contribution/styleguide.mdx +++ b/src/content/docs/contribution/styleguide.mdx @@ -19,14 +19,12 @@ 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. + 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. @@ -35,19 +33,7 @@ On the other hand, including small details that you'd only discover through actu 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. + It's a lifesaver for teams without experience, and reduces the review workload on software mentors with experience. ## Inspired by gm0's Style Guide @@ -56,26 +42,26 @@ 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 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 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 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. + 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 @@ -102,14 +88,6 @@ However, try avoiding excessively using it. ### 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)` ### Linting and Formatting diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 502bc05..ba50651 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -16,8 +16,28 @@ hero: import HomeCard from '../../components/HomeCard.astro';
- - + + + +
diff --git a/src/starlightOverrides/Header.astro b/src/starlightOverrides/Header.astro index 4e02d83..deb2bc9 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;