diff --git a/Docs/1_General/1.2_BasicGit.md b/Docs/1_General/1.2_BasicGit.md index 49dee4e..b0678f8 100644 --- a/Docs/1_General/1.2_BasicGit.md +++ b/Docs/1_General/1.2_BasicGit.md @@ -3,11 +3,12 @@ ## Git is a version control system, or a way for us to collaborate on code and manage having multiple versions of code working in parallel While many modern cloud applications, like google docs, have some form of auto-save to the cloud, we don't necessarily want a single auto-updating version of our code. -Instead we use a tool called Git to manage different versions of our files and save them to Github, which lets us share the codebase between computers. +As we're working, the changes we make can cause code to break very quickly in ways that might not be immediately obvious, which means it's good to be able to take a "snapshot" of the code at a point where it worked. +So, we use a tool called Git to manage different versions of our files and save them to Github, which lets us share the codebase between computers. Instead of automatically syncing to Github, we save our code in small named chunks called commits. -The named versions makes it easy to revert changes that break previously working behaviour and see when and by who code was written. -Git also lets us have different versions, called branches, in progress in parallel. -This means that while one person works on code for the autonomous, another could work on vision, for example. +These named versions makes it easy to revert changes that break previously working behaviour and see when and by who code was written. +Git also lets us have different, parallel versions, called branches, of code. +This means that while one person works on code for the autonomous, another could work on vision, for example, without overriding each other. ### Resources @@ -15,7 +16,7 @@ Read one of the following: - [WPILib Git intro](https://docs.wpilib.org/en/stable/docs/software/basic-programming/git-getting-started.html) - [Github Git intro](https://docs.github.com/en/get-started/using-git/about-git) -- _Record quick intro to git vid/talk at some point, talk to kevin or a software lead until then if you prefer a non-text intro_ +- [Github Git intro video (start at 0:43)](https://youtu.be/r8jQ9hVA2qs?t=43) Install the following: @@ -24,16 +25,18 @@ Install the following: ### Examples -- ![A simple demonstration of commiting and pushing some changes in git](../../Assets/GitExample.png) -- Typing `git add .` then `git commit -m "commit name"` then `git push` is the bread and butter of using git. - This sequence takes all of your uncommited changes and commits them, then pushes them to github +![A simple demonstration of committing and pushing some changes in git](../../Assets/GitExample.png) + +- Typing `git add .` then `git commit -m "commit name"` then `git push` is the bread and butter of using Git. + This sequence tells Git to collect all of your uncommitted changes, commit them, then push them to Github. + If you'd like to combine these into one command, you can add an alias to your .gitconfig file (ask a lead or mentor for help). - `git checkout branch-name` switches between branches - `git checkout -b new-branch` makes a new branch and switches to it. Note that the first time you push from this branch you will need to enter some extra parameters, but the terminal should prompt you with the correct command when you enter `git push` -- `git status` displays the current branch and what changes you have uncommited and staged +- `git status` displays the current branch and what changes you have uncommitted and staged - `git pull` updates the code on your device with the latest code from Github. Recommended to do this whenever someone else has been working on the same branch, otherwise you might make conflicting changes -- [A simple demo video of commiting some changes](../../Assets/GitDemoVideo.mp4) +- [A simple demo video of committing some changes](../../Assets/GitDemoVideo.mp4) ### Exercises @@ -48,17 +51,17 @@ Install the following: - We use GitHub's pull request (PR) feature to manage branches and merges. Always make sure to merge to main using a PR. -PR's will be explained further in the Git Workflow docs. -- Always commit code that at the very least compiles (you can check this by running the "Build robot code" option in WPILibs command bar) -- Commit messages should be short and simple, ~10 words is a good target. +PR's will be explained further in the [Git Workflow docs](Docs/1_General/1.3_GitWorkflow.md). +- Always commit code that at the very least compiles (you can check this by running the "Build robot code" option in WPILib's command bar) +- Commit messages should be short (~10 words), simple, and descriptive. If it's too long, use multiple lines in the commit message -- Commits should be frequent, whenever you reach a working state you should commit before you accidentaly break anything again -- Commiting directly to the `main` branch is frowned upon. - `main` should always contain working code when possible and features should be developed on separate branches and merged/pull requested in -- **ALWAYS ALWAYS ALWAYS** commit before you leave a meeting, especially if you are using a team computer. - It is never fun to have to commit someone else's code at the start of the day or find out an hour in that you've been working off of someone elses uncommited (potentially broken!) code. - Uncommited code also makes it harder to track what is and isn't finished -- Run a `git status` at the start of a meeting to make sure whoever was there before you commited their code and that you are on the right branch +- Commits should be frequent. Whenever you reach a working state, you should commit before you accidentally break anything again +- Don't commit directly to the `main` branch, as `main` should **always** contain working code. + New code should be developed on separate branches and can only be merged through a pull request after being reviewed and approved. +- **ALWAYS ALWAYS ALWAYS** commit before you leave a meeting, especially if you are using a team computer! + It is never fun to have to commit someone else's code at the start of the day or find out an hour in that you've been working off of someone else's uncommitted (potentially broken!) code. + Uncommitted code also makes it harder to track what is and isn't finished. +- Run a `git status` at the start of a meeting to make sure whoever was there before you committed their code and that you are on the right branch ### Names @@ -68,7 +71,7 @@ PR's will be explained further in the Git Workflow docs. - Aliya - Athena - Jerry -- Nathan (8/15/24) +- Nathan - Sam - Viviane - Jeffery diff --git a/Docs/1_General/1.3_GitWorkflow.md b/Docs/1_General/1.3_GitWorkflow.md index 2ca2cf8..ed86c4c 100644 --- a/Docs/1_General/1.3_GitWorkflow.md +++ b/Docs/1_General/1.3_GitWorkflow.md @@ -19,31 +19,44 @@ Right now, this branch is only local to your computer. To upload this branch to the remote repository so others can view it: `git push --set-upstream origin ` -Once you have pushed the branch for the first time, it should show up on GitHub and be accessable by others. -You can and should use `git push` without the rest to push any further commits. +Once you have pushed the branch for the first time, it should show up on GitHub and be accessible by others. +Use `git push` without the rest to push any further commits. ## Pull Requests -Pull requests and other organization practices are crucial to write maintainable, clean code +Pull requests (PRs) are crucial to write maintainable, clean code. +A pull request is a way to get a review from others on changes before merging them to the main branch. +To ensure that we always have working and tested code on main, pull requests are required to merge code into main on our season repositories. -A pull request (PR) is a way to get review on changes before merging them to the main branch. To make a pull request, first you need to have changes to merge. These changes should be on their own, well named branch. -Then go to the pull requests tab on the github repo and hit `new pull request`. +Then go to the pull requests tab on the Github repo and hit `new pull request`. You should be prompted to compare a branch with main. Select the branch you want to merge. You should see a list of changes and a green button that says `Create pull request`. -Click that button and then let a software lead or mentor know that you need review. +Click that button, then let a software lead or mentor know that you need review and request them in Github. ## Issues Issues are a way to track features that we want to add and problems we need to fix in the repository. -Issues can be created by going to the issues tab of the repository on github and clicking `New issue`. -PRs can be linked to issues to show that an issue has been worked on and automatically resolve the issue when the PR is merged. -While our use of Issues is somewhat sporadic, they are useful for managing work. +Issues can be created by going to the issues tab of the repository on Github and clicking `New issue`. If there is a relevant issue for something you are working on, make sure to keep it up to date! If you have something that you think should be added or fixed, open an issue! +## Github Projects +Similar to the Slack lists we use for other projects on the team, the robot software subteam uses Github Projects to manage projects and delegate tasks. +You can access the Project for each repository in its own tab at the top, and add tasks organized by the status columns. + +Tasks that are explicitly about a specific PR should be converted to an issue and linked to that PR. +This will automatically resolve the issue when the PR is merged and move the task to the Completed column. +Important milestones (handoff day, our first competition), major features (add preliminary autos, add intake subsystem), and bugfixes/improvements (improve vision filtering, fix 4 piece auto) should all go in the Project. +Leads are expected to add these kinds of major deadlines as soon as they're coordinated, and monitor subteam member progress frequently. + +During the commotion of the build season, it is very easy to lose track of what needs to be done, who is supposed to be doing it, and when it needs to be done, and so it doesn't get done. (Ask Kevin about the tragedy of the commons.) +Hence, **it is expected** that you regularly **enter** events, task assignments, and deadlines so this can accurately reflect what we're working on. +It is also expected that you regularly **check** what has been assigned to you. +If you feel unsure of what you need to do, ask a lead or mentor ASAP! + ### Resources - [Github creating a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) @@ -70,6 +83,3 @@ If you have something that you think should be added or fixed, open an issue! - Nathan - Vivie - Jeffery -### Notes - -- We use pull requests to make sure our code is readable and maintainable by having regular review of code.