Update "Getting Started" and software architecture docs #3313

williamckha · 2024-09-08T19:54:17Z

Description

Testing Done

Resolved Issues

Resolves #1854
Resolves #3312
Resolves #3126

Length Justification and Key Files to Review

Review Checklist

It is the reviewers responsibility to also make sure every item here has been covered

Function & Class comments: All function definitions (usually in the .h file) should have a javadoc style comment at the start of them. For examples, see the functions defined in thunderbots/software/geom. Similarly, all classes should have an associated Javadoc comment explaining the purpose of the class.
Remove all commented out code
Remove extra print statements: for example, those just used for testing
Resolve all TODO's: All TODO (or similar) statements should either be completed or associated with a github issue

…into update_docs

docs/getting-started.md

docs/software-architecture-and-design.md

itsarune

2 minor nits

notion-workspace · 2024-09-21T03:14:00Z

New page

github-actions · 2024-10-26T02:58:04Z

This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

…into update_docs

docs/software-architecture-and-design.md

docs/getting-started.md

docs/software-architecture-and-design.md

scripts/lint_and_format.sh

github-actions · 2025-02-04T02:55:52Z

This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

Andrewyx · 2025-03-01T20:11:56Z

src/software/embedded/primitive_executor.h

+#include "software/time/duration.h"
+#include "software/world/robot_state.h"
+#include "software/world/team_types.h"


why are these added now?

i think these includes are necessary, ci fails to build without them

ah I see what I did, instead of including world.h, I changed it so that we only include the header files that are actually necessary

…into update_docs

This reverts commit f127f5c.

williamckha · 2025-04-09T03:30:45Z

@itsarune @sauravbanna please approve, no changes since last review

github-actions · 2025-05-10T03:22:55Z

This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

github-actions · 2025-05-15T03:27:29Z

This PR was closed because it has been stalled for 5 days with no activity.

itsarune · 2025-06-02T23:48:59Z

docs/getting-started.md

+11. Make sure our automated tests with Github Actions are passing. There will be an indicator near the bottom of the Pull Request. If something fails, you can click on the links provided to get more information and debug the problems.
 12. Once your Pull Request has been approved and the automated tests pass, you can merge the code. There will be a big 'merge" button at the bottom of the Pull Request with several options to choose from
-    1. We only allow "Squash and merge". This is because it keep the commit history on `upstream/master` shorter and cleaner, without losing any context from the commit messages (since they are combined in the squashed commit. A squashed commit also makes it easier to revert and entire change/feature, rather than having to "know" the range of commits to revert.
+    1. We only allow "Squash and merge". This is because it keeps the commit history on `upstream/master` shorter and cleaner, without losing any context from the commit messages (since they are combined in the squashed commit. A squashed commit also makes it easier to revert and entire change/feature, rather than having to "know" the range of commits to revert.


Suggested change

1. We only allow "Squash and merge". This is because it keeps the commit history on `upstream/master` shorter and cleaner, without losing any context from the commit messages (since they are combined in the squashed commit. A squashed commit also makes it easier to revert and entire change/feature, rather than having to "know" the range of commits to revert.

1. We only allow "Squash and merge". This is because it keeps the commit history on `upstream/master` shorter and cleaner, without losing any context from the commit messages (since they are combined in the squashed commit. A squashed commit also makes it easier to revert an entire change/feature, rather than having to "know" the range of commits to revert.

itsarune · 2025-06-02T23:55:15Z

docs/software-architecture-and-design.md

@@ -142,100 +123,341 @@ The `TbotsProto::RobotStatus` protobuf message contains information about the st
 * The capacitor charge on the robot
 * The temperature of the dribbler motor


idk when this was written but we've never communicated the "temperature of the dribbler motor" 😆

itsarune · 2025-06-03T00:11:40Z

docs/software-architecture-and-design.md

@@ -249,39 +471,43 @@ int main() {
 Lets walk through what's happening here:
 1. The first time the `fib` function is called, the variables `f1` and `f2` are initialized, and we go through the first iteration of the loop until `yield` is encountered
 2. The `yield` statement is going to return the currently computed value of the fibonacci sequence (the variable `fn`) and save the state of the `fib` function
-    * "yielding" the data here is effectively returning it so that the code in the `main` function can print the result
+* "yielding" the data here is effectively returning it so that the code in the `main` function can print the result


why remove the tab here?

itsarune · 2025-06-03T00:11:49Z

docs/software-architecture-and-design.md

 3. The second time `main()` calls the `fib()` function, the function will resume immediately after the `yield()` statement. This means that execution will go back to the top of the loop, *and still remember the values of `f1` and `f2` from the last time the function was called*. Since the coroutine saved the function state, it still has the previous values of `f1` and `f2` which it uses to compute the next value in the sequence.
 4. Once again when the `yield()` statement is reached, the newly computed value is returned and the function state is saved. You can think of this as "pausing" the function.
 5. As `main()` keeps calling the `fib()` function, it is computing and returning the values of the fibonacci sequence, and this only works because the coroutine "remembers" the values from each previous fibonacci computation which it uses to compute the next value the next time the function is called.
-    * If the `yield` was replaced with a regular `return` statement, the function would only ever return the value `1`. This is because using `return` would not save the function state, so the next time it's called the function would start at the beginning again, and only ever compute the first value of the sequence.
+* If the `yield` was replaced with a regular `return` statement, the function would only ever return the value `1`. This is because using `return` would not save the function state, so the next time it's called the function would start at the beginning again, and only ever compute the first value of the sequence.


why remove the tab here?

itsarune · 2025-06-03T00:24:48Z

docs/software-architecture-and-design.md


-`Applicable` indicates when a `Play` can be started. For example, we would not want to start a `Defense Play` if our team is in possession of the ball. The `Invariant` condition is a condition that must always be met for the `Play` to continue running. If this condition ever becomes false, the current `Play` will stop running and a new one will be chosen. For example, once we start running a friendly `Corner Kick` play, we want the `Play` to continue running as long as the enemy team does not have possession of the ball.
+We check whether a trajectory collides with any obstacles on the field by stepping over the trajectory in fixed steps (e.g. 100 ms) and checking whether the trajectory's position at any step lies inside an obstacle. We penalize a trajectory's score based on the amount of time until the first collision. This is because a collision that occurs earlier in a trajectory is more likely to happen (for real) compared to a collision occurring later in a trajectory, since obstacles may move and the state of the World may change by the time that later collision would have happened. That is, we cannot reliably predict where obstacles will be in the faraway future, so we are less harsh in penalizing trajectories with late collisions.


Suggested change

We check whether a trajectory collides with any obstacles on the field by stepping over the trajectory in fixed steps (e.g. 100 ms) and checking whether the trajectory's position at any step lies inside an obstacle. We penalize a trajectory's score based on the amount of time until the first collision. This is because a collision that occurs earlier in a trajectory is more likely to happen (for real) compared to a collision occurring later in a trajectory, since obstacles may move and the state of the World may change by the time that later collision would have happened. That is, we cannot reliably predict where obstacles will be in the faraway future, so we are less harsh in penalizing trajectories with late collisions.

We check whether a trajectory collides with any obstacles on the field by stepping over the trajectory in fixed steps (e.g. 100 ms) and checking whether the trajectory's position at any step lies inside an obstacle. We penalize a trajectory's score based on the amount of time until the first collision. This is because a collision that occurs earlier in a trajectory is more likely to happen (for real) compared to a collision occurring later in a trajectory, since obstacles may move and the state of the [World](#world) may change by the time that later collision would have happened. That is, we cannot reliably predict where obstacles will be in the faraway future, so we are less harsh in penalizing trajectories with late collisions.

itsarune

LGTM I think syncing with master will fix your failing CI? IIRC this error is related to a merge conflict

…into update_docs

williamckha · 2025-06-11T16:53:31Z

The remaining requested changes can be made in #3455

williamckha added 9 commits August 4, 2024 21:20

Docs update

877199e

Update getting-started-wsl.md

7923f40

Update getting-started-wsl.md

a33d33f

Update PR template

513d2d6

Getting Started changes

d8c7559

Merge branch 'master' of https://github.com/UBC-Thunderbots/Software …

a935c64

…into update_docs

Merge branch 'master' of https://github.com/UBC-Thunderbots/Software …

0b9ef6c

…into update_docs

Update wsl instructions

ecc921d

Update docs

e65839a

williamckha added the Documentation Issues involving documentation label Sep 8, 2024

williamckha requested review from itsarune and sauravbanna as code owners September 8, 2024 19:54

itsarune reviewed Sep 18, 2024

View reviewed changes

docs/getting-started.md Outdated Show resolved Hide resolved

itsarune reviewed Sep 18, 2024

View reviewed changes

docs/software-architecture-and-design.md Outdated Show resolved Hide resolved

itsarune reviewed Sep 18, 2024

View reviewed changes

Address comments

56eaa49

Remove scripts for installing CLion and VS Code

3df8f40

github-actions bot added the Stale Inactive pull requests label Oct 26, 2024

williamckha removed the Stale Inactive pull requests label Oct 26, 2024

williamckha added 2 commits October 27, 2024 22:12

Merge branch 'master' of https://github.com/UBC-Thunderbots/Software …

fed4603

…into update_docs

Add markdown table of contents generator to lint_and_format.sh

5022a95

itsarune reviewed Nov 4, 2024

View reviewed changes

docs/software-architecture-and-design.md Outdated Show resolved Hide resolved

itsarune reviewed Nov 4, 2024

View reviewed changes

docs/getting-started.md Outdated Show resolved Hide resolved

itsarune reviewed Nov 4, 2024

View reviewed changes

docs/getting-started.md Outdated Show resolved Hide resolved

itsarune reviewed Nov 4, 2024

View reviewed changes

docs/software-architecture-and-design.md Outdated Show resolved Hide resolved

itsarune reviewed Nov 4, 2024

View reviewed changes

docs/software-architecture-and-design.md Outdated Show resolved Hide resolved

itsarune reviewed Nov 4, 2024

View reviewed changes

scripts/lint_and_format.sh Show resolved Hide resolved

Rename command-line to command line when it is a noun

82c9a05

github-actions bot added the Stale Inactive pull requests label Jan 4, 2025

williamckha removed the Stale Inactive pull requests label Jan 5, 2025

github-actions bot added the Stale Inactive pull requests label Feb 4, 2025

williamckha removed the Stale Inactive pull requests label Feb 4, 2025

Andrewyx reviewed Mar 1, 2025

View reviewed changes

williamckha added 2 commits March 8, 2025 14:55

Remove includes in primitive_executor.h

f127f5c

Merge branch 'master' of https://github.com/UBC-Thunderbots/Software …

be74d55

…into update_docs

williamckha dismissed itsarune’s stale review via be74d55 March 8, 2025 22:56

williamckha requested review from Andrewyx and itsarune March 8, 2025 22:58

pre-commit-ci-lite bot and others added 2 commits March 8, 2025 23:05

[pre-commit.ci lite] apply automatic fixes

7e5d73b

Revert "Remove includes in primitive_executor.h"

3eb22fb

This reverts commit f127f5c.

Mr-Anyone approved these changes Mar 15, 2025

View reviewed changes

github-actions bot added the Stale Inactive pull requests label May 10, 2025

github-actions bot closed this May 15, 2025

williamckha reopened this May 15, 2025

williamckha removed the Stale Inactive pull requests label May 15, 2025

itsarune reviewed Jun 2, 2025

View reviewed changes

itsarune reviewed Jun 3, 2025

View reviewed changes

itsarune approved these changes Jun 3, 2025

View reviewed changes

Merge branch 'master' of https://github.com/UBC-Thunderbots/Software …

d4077e5

…into update_docs

williamckha merged commit 7e27714 into UBC-Thunderbots:master Jun 11, 2025
6 checks passed

	1. We only allow "Squash and merge". This is because it keeps the commit history on `upstream/master` shorter and cleaner, without losing any context from the commit messages (since they are combined in the squashed commit. A squashed commit also makes it easier to revert and entire change/feature, rather than having to "know" the range of commits to revert.
	1. We only allow "Squash and merge". This is because it keeps the commit history on `upstream/master` shorter and cleaner, without losing any context from the commit messages (since they are combined in the squashed commit. A squashed commit also makes it easier to revert an entire change/feature, rather than having to "know" the range of commits to revert.

		@@ -142,100 +123,341 @@ The `TbotsProto::RobotStatus` protobuf message contains information about the st
		* The capacitor charge on the robot
		* The temperature of the dribbler motor


		`Applicable` indicates when a `Play` can be started. For example, we would not want to start a `Defense Play` if our team is in possession of the ball. The `Invariant` condition is a condition that must always be met for the `Play` to continue running. If this condition ever becomes false, the current `Play` will stop running and a new one will be chosen. For example, once we start running a friendly `Corner Kick` play, we want the `Play` to continue running as long as the enemy team does not have possession of the ball.
		We check whether a trajectory collides with any obstacles on the field by stepping over the trajectory in fixed steps (e.g. 100 ms) and checking whether the trajectory's position at any step lies inside an obstacle. We penalize a trajectory's score based on the amount of time until the first collision. This is because a collision that occurs earlier in a trajectory is more likely to happen (for real) compared to a collision occurring later in a trajectory, since obstacles may move and the state of the World may change by the time that later collision would have happened. That is, we cannot reliably predict where obstacles will be in the faraway future, so we are less harsh in penalizing trajectories with late collisions.

Update "Getting Started" and software architecture docs #3313

Update "Getting Started" and software architecture docs #3313

Uh oh!

Conversation

williamckha commented Sep 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing Done

Resolved Issues

Length Justification and Key Files to Review

Review Checklist

Uh oh!

Uh oh!

Uh oh!

itsarune left a comment

Choose a reason for hiding this comment

Uh oh!

notion-workspace bot commented Sep 21, 2024

Uh oh!

github-actions bot commented Oct 26, 2024

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

williamckha commented Apr 9, 2025

Uh oh!

github-actions bot commented May 10, 2025

Uh oh!

github-actions bot commented May 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itsarune left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

williamckha commented Jun 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

williamckha commented Sep 8, 2024 •

edited

Loading