From 58148313572272e35f632f4e67ff603c4ea570cb Mon Sep 17 00:00:00 2001 From: Joseph Eng <91924258+KangarooKoala@users.noreply.github.com> Date: Thu, 5 Jun 2025 17:01:02 -0700 Subject: [PATCH 1/6] Add information about watching changes --- source/docs/contributing/watching-changes.rst | 44 +++++++++++++++++++ source/index.rst | 1 + 2 files changed, 45 insertions(+) create mode 100644 source/docs/contributing/watching-changes.rst diff --git a/source/docs/contributing/watching-changes.rst b/source/docs/contributing/watching-changes.rst new file mode 100644 index 0000000000..a0bcff51cd --- /dev/null +++ b/source/docs/contributing/watching-changes.rst @@ -0,0 +1,44 @@ +# Watching changes + +This document describes different ways to stay up-to-date on the changes being made to the WPILib suite. + +## Stages of development + +To provide context about the different ways to stay up to date, below are the relevant stages of development: + +- Discord: The [Unofficial FIRST Robotics Competition Discord Server](https://discord.com/invite/frc) contains a programming discussion channel where people bring up their initial ideas and then receive feedback on them, either fleshing them out or learning why they might not be good ideas. Most of the major changes will have some discussion in here, but not all. +- GitHub issue: Issues on the relevant GitHub repository are the next step toward a change being implemented. If the idea has gone through Discord, then this simply presents the fleshed out idea; Otherwise, this presents the idea and sometimes get initial discussion. Sometimes changes will skip this step and move straight to a pull request. +- GitHub design document: Very major changes will first create a design doc in a pull request to the relevant GitHub repository. Compared to a GitHub issue, a design doc provides a more specific and detailed description of both the changes and the throught process. Only very major features or changes will create a design doc, and sometimes a design doc is included in the pull request implementing the changes. +- GitHub pull request: A pull request implements the changes and gets reviewed by members of the WPILib team. Every change is implemented through a pull request. +- GitHub commits: After a pull request is reviewed and merged, it shows up in the list of commits to that repository. Every change will show up in the commit list of the relevant branch. +- Release notes: New releases are accompanied by release notes, which summarize all of the changes made since the previous release with links to the pull requests implementing them. There is also :doc:`a yearly changelog ` summarizing the changes made between years. +- Beta testing: Between competition seasons are beta periods where teams can test the new changes, providing feedback about bugs or ways to improve the team experience. + +## Discussing proposed changes + +To provide feedback as soon as possible about proposed changes, you will need to be active where the initial discussion happens. This initial discussion usually happens in the Unofficial FIRST Robotics Competition Discord Server, but sometimes it happens in GitHub issues or directly in GitHub pull requests. + +## Viewing in-progress changes + +Every change must be implemented through a GitHub pull request, so watching the pull requests will ensure you see all changes being made. + +There are two useful tools for watching pull requests or issues: +- The GitHub issues and pull requests pages provide a ``updated:>=YYYY-MM-DD`` filter that shows changes made since a particular date. If you record the last day you checked, you can ensure you catch up on all issues or pull requests. +- The GitHub repository page provides a [watch feature](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) that allows you to subscribe to notifications on that repository. To select just issues and/or pull requests, select the "Custom" option. + +## Seeing implemented changes + +To stay up to date on what changes have been made, you have two options based on how often you want to check. To see new changes as soon as possible, check the commit history of the active branches. Commits tend to be made in batches, so most days there are no new commits, making this very low effort. For an even lower effort method, you can check the release notes or yearly changelog. + +## Testing changes + +To test the new changes for the upcoming season, test out the beta versions. It is also possible to test out the changes before the beta period starts, but it takes more work. See [Using Development Builds](https://github.com/wpilibsuite/allwpilib/blob/main/DevelopmentBuilds.md) on the allwpilib repository for details. + +## Quick links + +Below are some useful links for staying up to date: + +- [WPILib issues page](https://github.com/wpilibsuite/allwpilib/issues) +- [WPILib pull requests page](https://github.com/wpilibsuite/allwpilib/pulls) +- [WPILib commits to main](https://github.com/wpilibsuite/allwpilib/commits/main/) +- [WPILib releases page](https://github.com/wpilibsuite/allwpilib/tags) diff --git a/source/index.rst b/source/index.rst index b1b7c18731..ff6f0e6486 100644 --- a/source/index.rst +++ b/source/index.rst @@ -440,6 +440,7 @@ Community translations can be found in a variety of languages in the menu toward docs/contributing/frc-docs/index docs/contributing/wpilib/index + docs/contributing/watching-changes .. toctree:: :maxdepth: 1 From b5002fc0ac56824bdfc9298440acf0293c3532d8 Mon Sep 17 00:00:00 2001 From: Joseph Eng <91924258+KangarooKoala@users.noreply.github.com> Date: Fri, 6 Jun 2025 14:52:25 -0700 Subject: [PATCH 2/6] Update wording Provide more detail about Discord vs GitHub issues Add more detail about the order of events --- source/docs/contributing/watching-changes.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/docs/contributing/watching-changes.rst b/source/docs/contributing/watching-changes.rst index a0bcff51cd..01e60132fa 100644 --- a/source/docs/contributing/watching-changes.rst +++ b/source/docs/contributing/watching-changes.rst @@ -4,16 +4,18 @@ This document describes different ways to stay up-to-date on the changes being m ## Stages of development -To provide context about the different ways to stay up to date, below are the relevant stages of development: +To provide context about the different ways to stay up to date, below are the stages of development in the typical order: -- Discord: The [Unofficial FIRST Robotics Competition Discord Server](https://discord.com/invite/frc) contains a programming discussion channel where people bring up their initial ideas and then receive feedback on them, either fleshing them out or learning why they might not be good ideas. Most of the major changes will have some discussion in here, but not all. -- GitHub issue: Issues on the relevant GitHub repository are the next step toward a change being implemented. If the idea has gone through Discord, then this simply presents the fleshed out idea; Otherwise, this presents the idea and sometimes get initial discussion. Sometimes changes will skip this step and move straight to a pull request. +- Discord: The [Unofficial FIRST Robotics Competition Discord Server](https://discord.com/invite/frc) contains a programming discussion channel where people bring up their initial ideas and then receive feedback on them, either fleshing them out or learning why they might not be good ideas. It is a popular location for quick iteration because of the live messaging nature of the platform and the number of WPILib developers who are active there. (Conversely, it can be tricky to read because of side conversations and sheer volume of messages, and the live messaging nature of the platform can lead to poorly thought out messages.) Most of the major changes will have some discussion in here, but not all. +- GitHub issue: Issues on the relevant GitHub repository provide wider visibility and better searchability and organization compared to Discord. If the idea has gone through Discord, then this simply presents the fleshed out idea; Otherwise, this presents the idea and sometimes get initial discussion. Sometimes changes will skip this step and move straight to a pull request. - GitHub design document: Very major changes will first create a design doc in a pull request to the relevant GitHub repository. Compared to a GitHub issue, a design doc provides a more specific and detailed description of both the changes and the throught process. Only very major features or changes will create a design doc, and sometimes a design doc is included in the pull request implementing the changes. - GitHub pull request: A pull request implements the changes and gets reviewed by members of the WPILib team. Every change is implemented through a pull request. - GitHub commits: After a pull request is reviewed and merged, it shows up in the list of commits to that repository. Every change will show up in the commit list of the relevant branch. - Release notes: New releases are accompanied by release notes, which summarize all of the changes made since the previous release with links to the pull requests implementing them. There is also :doc:`a yearly changelog ` summarizing the changes made between years. - Beta testing: Between competition seasons are beta periods where teams can test the new changes, providing feedback about bugs or ways to improve the team experience. +Occassionally, these events will happen out of order, most commonly when people use Discord to discuss a GitHub design document or pull request. + ## Discussing proposed changes To provide feedback as soon as possible about proposed changes, you will need to be active where the initial discussion happens. This initial discussion usually happens in the Unofficial FIRST Robotics Competition Discord Server, but sometimes it happens in GitHub issues or directly in GitHub pull requests. From 52a6c4eca12b775bc182013e10cc406ff9bfd3df Mon Sep 17 00:00:00 2001 From: Joseph Eng <91924258+KangarooKoala@users.noreply.github.com> Date: Fri, 6 Jun 2025 14:54:31 -0700 Subject: [PATCH 3/6] Fix list --- source/docs/contributing/watching-changes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/docs/contributing/watching-changes.rst b/source/docs/contributing/watching-changes.rst index 01e60132fa..77d3acba0e 100644 --- a/source/docs/contributing/watching-changes.rst +++ b/source/docs/contributing/watching-changes.rst @@ -25,6 +25,7 @@ To provide feedback as soon as possible about proposed changes, you will need to Every change must be implemented through a GitHub pull request, so watching the pull requests will ensure you see all changes being made. There are two useful tools for watching pull requests or issues: + - The GitHub issues and pull requests pages provide a ``updated:>=YYYY-MM-DD`` filter that shows changes made since a particular date. If you record the last day you checked, you can ensure you catch up on all issues or pull requests. - The GitHub repository page provides a [watch feature](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) that allows you to subscribe to notifications on that repository. To select just issues and/or pull requests, select the "Custom" option. From ed108c0ee5f01f85419d4d1b076b15878a3c624c Mon Sep 17 00:00:00 2001 From: Joseph Eng <91924258+KangarooKoala@users.noreply.github.com> Date: Fri, 6 Jun 2025 14:56:15 -0700 Subject: [PATCH 4/6] Bold the different stages Helps deal with feeling like a wall of text --- source/docs/contributing/watching-changes.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/docs/contributing/watching-changes.rst b/source/docs/contributing/watching-changes.rst index 77d3acba0e..76fe2cafe2 100644 --- a/source/docs/contributing/watching-changes.rst +++ b/source/docs/contributing/watching-changes.rst @@ -6,13 +6,13 @@ This document describes different ways to stay up-to-date on the changes being m To provide context about the different ways to stay up to date, below are the stages of development in the typical order: -- Discord: The [Unofficial FIRST Robotics Competition Discord Server](https://discord.com/invite/frc) contains a programming discussion channel where people bring up their initial ideas and then receive feedback on them, either fleshing them out or learning why they might not be good ideas. It is a popular location for quick iteration because of the live messaging nature of the platform and the number of WPILib developers who are active there. (Conversely, it can be tricky to read because of side conversations and sheer volume of messages, and the live messaging nature of the platform can lead to poorly thought out messages.) Most of the major changes will have some discussion in here, but not all. -- GitHub issue: Issues on the relevant GitHub repository provide wider visibility and better searchability and organization compared to Discord. If the idea has gone through Discord, then this simply presents the fleshed out idea; Otherwise, this presents the idea and sometimes get initial discussion. Sometimes changes will skip this step and move straight to a pull request. -- GitHub design document: Very major changes will first create a design doc in a pull request to the relevant GitHub repository. Compared to a GitHub issue, a design doc provides a more specific and detailed description of both the changes and the throught process. Only very major features or changes will create a design doc, and sometimes a design doc is included in the pull request implementing the changes. -- GitHub pull request: A pull request implements the changes and gets reviewed by members of the WPILib team. Every change is implemented through a pull request. -- GitHub commits: After a pull request is reviewed and merged, it shows up in the list of commits to that repository. Every change will show up in the commit list of the relevant branch. -- Release notes: New releases are accompanied by release notes, which summarize all of the changes made since the previous release with links to the pull requests implementing them. There is also :doc:`a yearly changelog ` summarizing the changes made between years. -- Beta testing: Between competition seasons are beta periods where teams can test the new changes, providing feedback about bugs or ways to improve the team experience. +- **Discord**: The [Unofficial FIRST Robotics Competition Discord Server](https://discord.com/invite/frc) contains a programming discussion channel where people bring up their initial ideas and then receive feedback on them, either fleshing them out or learning why they might not be good ideas. It is a popular location for quick iteration because of the live messaging nature of the platform and the number of WPILib developers who are active there. (Conversely, it can be tricky to read because of side conversations and sheer volume of messages, and the live messaging nature of the platform can lead to poorly thought out messages.) Most of the major changes will have some discussion in here, but not all. +- **GitHub issue**: Issues on the relevant GitHub repository provide wider visibility and better searchability and organization compared to Discord. If the idea has gone through Discord, then this simply presents the fleshed out idea; Otherwise, this presents the idea and sometimes get initial discussion. Sometimes changes will skip this step and move straight to a pull request. +- **GitHub design document**: Very major changes will first create a design doc in a pull request to the relevant GitHub repository. Compared to a GitHub issue, a design doc provides a more specific and detailed description of both the changes and the throught process. Only very major features or changes will create a design doc, and sometimes a design doc is included in the pull request implementing the changes. +- **GitHub pull request**: A pull request implements the changes and gets reviewed by members of the WPILib team. Every change is implemented through a pull request. +- **GitHub commits**: After a pull request is reviewed and merged, it shows up in the list of commits to that repository. Every change will show up in the commit list of the relevant branch. +- **Release notes**: New releases are accompanied by release notes, which summarize all of the changes made since the previous release with links to the pull requests implementing them. There is also :doc:`a yearly changelog ` summarizing the changes made between years. +- **Beta testing**: Between competition seasons are beta periods where teams can test the new changes, providing feedback about bugs or ways to improve the team experience. Occassionally, these events will happen out of order, most commonly when people use Discord to discuss a GitHub design document or pull request. From 3d06d299b02f4e04d37dc65fda8254e3e21750ec Mon Sep 17 00:00:00 2001 From: Joseph Eng <91924258+KangarooKoala@users.noreply.github.com> Date: Fri, 6 Jun 2025 15:01:01 -0700 Subject: [PATCH 5/6] Adjust organization --- source/docs/contributing/watching-changes.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/source/docs/contributing/watching-changes.rst b/source/docs/contributing/watching-changes.rst index 76fe2cafe2..f10c9c5e78 100644 --- a/source/docs/contributing/watching-changes.rst +++ b/source/docs/contributing/watching-changes.rst @@ -16,11 +16,15 @@ To provide context about the different ways to stay up to date, below are the st Occassionally, these events will happen out of order, most commonly when people use Discord to discuss a GitHub design document or pull request. -## Discussing proposed changes +## Different ways to be involved + +Below are some common ways people want to be interact with upcoming changes and how to do so. + +### Discussing proposed changes To provide feedback as soon as possible about proposed changes, you will need to be active where the initial discussion happens. This initial discussion usually happens in the Unofficial FIRST Robotics Competition Discord Server, but sometimes it happens in GitHub issues or directly in GitHub pull requests. -## Viewing in-progress changes +### Viewing in-progress changes Every change must be implemented through a GitHub pull request, so watching the pull requests will ensure you see all changes being made. @@ -29,11 +33,11 @@ There are two useful tools for watching pull requests or issues: - The GitHub issues and pull requests pages provide a ``updated:>=YYYY-MM-DD`` filter that shows changes made since a particular date. If you record the last day you checked, you can ensure you catch up on all issues or pull requests. - The GitHub repository page provides a [watch feature](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) that allows you to subscribe to notifications on that repository. To select just issues and/or pull requests, select the "Custom" option. -## Seeing implemented changes +### Seeing implemented changes To stay up to date on what changes have been made, you have two options based on how often you want to check. To see new changes as soon as possible, check the commit history of the active branches. Commits tend to be made in batches, so most days there are no new commits, making this very low effort. For an even lower effort method, you can check the release notes or yearly changelog. -## Testing changes +### Testing changes To test the new changes for the upcoming season, test out the beta versions. It is also possible to test out the changes before the beta period starts, but it takes more work. See [Using Development Builds](https://github.com/wpilibsuite/allwpilib/blob/main/DevelopmentBuilds.md) on the allwpilib repository for details. From a92598b71d4f16073454782de6cfa9f01b593e42 Mon Sep 17 00:00:00 2001 From: Joseph Eng <91924258+KangarooKoala@users.noreply.github.com> Date: Fri, 6 Jun 2025 15:02:33 -0700 Subject: [PATCH 6/6] Adjust wording to be more like options --- source/docs/contributing/watching-changes.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/docs/contributing/watching-changes.rst b/source/docs/contributing/watching-changes.rst index f10c9c5e78..a933b532e2 100644 --- a/source/docs/contributing/watching-changes.rst +++ b/source/docs/contributing/watching-changes.rst @@ -18,15 +18,15 @@ Occassionally, these events will happen out of order, most commonly when people ## Different ways to be involved -Below are some common ways people want to be interact with upcoming changes and how to do so. +Below are some common ways people might want to be interact with upcoming changes and how they can do so. ### Discussing proposed changes -To provide feedback as soon as possible about proposed changes, you will need to be active where the initial discussion happens. This initial discussion usually happens in the Unofficial FIRST Robotics Competition Discord Server, but sometimes it happens in GitHub issues or directly in GitHub pull requests. +If you want to provide feedback as soon as possible about proposed changes, you will need to be active where the initial discussion happens. This initial discussion usually happens in the Unofficial FIRST Robotics Competition Discord Server, but sometimes it happens in GitHub issues or directly in GitHub pull requests. ### Viewing in-progress changes -Every change must be implemented through a GitHub pull request, so watching the pull requests will ensure you see all changes being made. +If you want to see all changes being made, you can watch the pull requests. (Note that every change must be implemented through a GitHub pull request.) There are two useful tools for watching pull requests or issues: @@ -35,11 +35,11 @@ There are two useful tools for watching pull requests or issues: ### Seeing implemented changes -To stay up to date on what changes have been made, you have two options based on how often you want to check. To see new changes as soon as possible, check the commit history of the active branches. Commits tend to be made in batches, so most days there are no new commits, making this very low effort. For an even lower effort method, you can check the release notes or yearly changelog. +If you want to stay up to date on what changes have been made, you have two options based on how often you want to check. To see new changes as soon as possible, check the commit history of the active branches. Commits tend to be made in batches, so most days there are no new commits, making this very low effort. For an even lower effort method, you can check the release notes or yearly changelog. ### Testing changes -To test the new changes for the upcoming season, test out the beta versions. It is also possible to test out the changes before the beta period starts, but it takes more work. See [Using Development Builds](https://github.com/wpilibsuite/allwpilib/blob/main/DevelopmentBuilds.md) on the allwpilib repository for details. +If you want to test the new changes for the upcoming season, you can test out the beta versions. It is also possible to test out the changes before the beta period starts, but it takes more work. See [Using Development Builds](https://github.com/wpilibsuite/allwpilib/blob/main/DevelopmentBuilds.md) on the allwpilib repository for details. ## Quick links