diff --git a/TeamCode/src/main/java/org/firstinspires/ftc/teamcode/readme.md b/TeamCode/src/main/java/org/firstinspires/ftc/teamcode/readme.md index 4d1da42..ee3146b 100644 --- a/TeamCode/src/main/java/org/firstinspires/ftc/teamcode/readme.md +++ b/TeamCode/src/main/java/org/firstinspires/ftc/teamcode/readme.md @@ -1,131 +1,150 @@ -## TeamCode Module +# Team FTC Git Workflow Guide -Welcome! +This document explains how to set up the FTC project on your computer and the rules for working with branches. -This module, TeamCode, is the place where you will write/paste the code for your team's -robot controller App. This module is currently empty (a clean slate) but the -process for adding OpModes is straightforward. +--- -## Creating your own OpModes +## 1. Cloning the Repository -The easiest way to create your own OpMode is to copy a Sample OpMode and make it your own. +1. Open a terminal (or the terminal inside Android Studio). +2. Navigate to the folder where you want to keep the project. +3. Run: -Sample opmodes exist in the FtcRobotController module. -To locate these samples, find the FtcRobotController module in the "Project/Android" tab. + ```bash + git clone https://github.com/KeshavAnandCode/DecodeFTCMain.git + cd DecodeFTCMain + ``` -Expand the following tree elements: - FtcRobotController/java/org.firstinspires.ftc.robotcontroller/external/samples +4. Verify your remotes: -### Naming of Samples + ```bash + git remote -v + ``` -To gain a better understanding of how the samples are organized, and how to interpret the -naming system, it will help to understand the conventions that were used during their creation. + You should see: + ``` + origin https://github.com/KeshavAnandCode/DecodeFTCMain.git (fetch) + origin https://github.com/KeshavAnandCode/DecodeFTCMain.git (push) + upstream https://github.com/FIRST-Tech-Challenge/FtcRobotController.git (fetch) + upstream https://github.com/FIRST-Tech-Challenge/FtcRobotController.git (push) + ``` -These conventions are described (in detail) in the sample_conventions.md file in this folder. +--- -To summarize: A range of different samples classes will reside in the java/external/samples. -The class names will follow a naming convention which indicates the purpose of each class. -The prefix of the name will be one of the following: +## 2. Keeping `master` Clean -Basic: This is a minimally functional OpMode used to illustrate the skeleton/structure - of a particular style of OpMode. These are bare bones examples. +- `master` should only contain clean, tested code. +- Nobody should ever code directly on `master`. +- To stay up to date: -Sensor: This is a Sample OpMode that shows how to use a specific sensor. - It is not intended to drive a functioning robot, it is simply showing the minimal code - required to read and display the sensor values. + ```bash + git checkout master + git fetch upstream + git merge upstream/master + git push origin master + ``` -Robot: This is a Sample OpMode that assumes a simple two-motor (differential) drive base. - It may be used to provide a common baseline driving OpMode, or - to demonstrate how a particular sensor or concept can be used to navigate. +--- -Concept: This is a sample OpMode that illustrates performing a specific function or concept. - These may be complex, but their operation should be explained clearly in the comments, - or the comments should reference an external doc, guide or tutorial. - Each OpMode should try to only demonstrate a single concept so they are easy to - locate based on their name. These OpModes may not produce a drivable robot. +## 3. Creating a Feature Branch -After the prefix, other conventions will apply: +Whenever you start a new task (feature, fix, experiment): -* Sensor class names are constructed as: Sensor - Company - Type -* Robot class names are constructed as: Robot - Mode - Action - OpModetype -* Concept class names are constructed as: Concept - Topic - OpModetype +1. Update `master` (see above). +2. Create a new branch from `master`: -Once you are familiar with the range of samples available, you can choose one to be the -basis for your own robot. In all cases, the desired sample(s) needs to be copied into -your TeamCode module to be used. + ```bash + git checkout master + git pull origin master + git checkout -b feature/short-description + ``` -This is done inside Android Studio directly, using the following steps: +### Branch Naming Standard - 1) Locate the desired sample class in the Project/Android tree. - - 2) Right click on the sample class and select "Copy" - - 3) Expand the TeamCode/java folder - - 4) Right click on the org.firstinspires.ftc.teamcode folder and select "Paste" - - 5) You will be prompted for a class name for the copy. - Choose something meaningful based on the purpose of this class. - Start with a capital letter, and remember that there may be more similar classes later. - -Once your copy has been created, you should prepare it for use on your robot. -This is done by adjusting the OpMode's name, and enabling it to be displayed on the -Driver Station's OpMode list. - -Each OpMode sample class begins with several lines of code like the ones shown below: +Branches **must** follow the format: ``` - @TeleOp(name="Template: Linear OpMode", group="Linear Opmode") - @Disabled +/ ``` -The name that will appear on the driver station's "opmode list" is defined by the code: - ``name="Template: Linear OpMode"`` -You can change what appears between the quotes to better describe your opmode. -The "group=" portion of the code can be used to help organize your list of OpModes. +Where `` is one of: +- `feature/` → new functionality +- `fix/` → bug fixes +- `experiment/` → prototypes or tests +- `docs/` → documentation updates +- `chore/` → maintenance or cleanup -As shown, the current OpMode will NOT appear on the driver station's OpMode list because of the - ``@Disabled`` annotation which has been included. -This line can simply be deleted , or commented out, to make the OpMode visible. +Examples: +- `feature/autonomous-path` +- `fix/motor-init` +- `experiment/vision-test` +- `docs/setup-instructions` +- `chore/gradle-update` +**Rules for names:** +- Use lowercase letters and hyphens (`-`) only. +- Keep it short but clear (3–5 words). +- One branch = one task. Never mix unrelated work. +--- -## ADVANCED Multi-Team App management: Cloning the TeamCode Module +## 4. Working on Your Branch -In some situations, you have multiple teams in your club and you want them to all share -a common code organization, with each being able to *see* the others code but each having -their own team module with their own code that they maintain themselves. +- Make changes in Android Studio. +- Stage and commit your changes: -In this situation, you might wish to clone the TeamCode module, once for each of these teams. -Each of the clones would then appear along side each other in the Android Studio module list, -together with the FtcRobotController module (and the original TeamCode module). + ```bash + git add . + git commit -m "short message about what changed" + ``` -Selective Team phones can then be programmed by selecting the desired Module from the pulldown list -prior to clicking to the green Run arrow. +- Push your branch to GitHub: -Warning: This is not for the inexperienced Software developer. -You will need to be comfortable with File manipulations and managing Android Studio Modules. -These changes are performed OUTSIDE of Android Studios, so close Android Studios before you do this. - -Also.. Make a full project backup before you start this :) + ```bash + git push origin feature/short-description + ``` -To clone TeamCode, do the following: +--- -Note: Some names start with "Team" and others start with "team". This is intentional. +## 5. Sharing Your Work -1) Using your operating system file management tools, copy the whole "TeamCode" - folder to a sibling folder with a corresponding new name, eg: "Team0417". +- Once your branch is ready: + 1. Open a Pull Request (PR) on GitHub to merge into `master`. + 2. At least one teammate should review before merging. -2) In the new Team0417 folder, delete the TeamCode.iml file. +--- -3) the new Team0417 folder, rename the "src/main/java/org/firstinspires/ftc/teamcode" folder - to a matching name with a lowercase 'team' eg: "team0417". +## 6. Branching Rules -4) In the new Team0417/src/main folder, edit the "AndroidManifest.xml" file, change the line that contains - package="org.firstinspires.ftc.teamcode" - to be - package="org.firstinspires.ftc.team0417" +**Do:** +- Always branch from `master`. +- Follow the naming standard exactly. +- Keep branches small and focused. +- Delete branches after they’re merged. -5) Add: include ':Team0417' to the "/settings.gradle" file. - -6) Open up Android Studios and clean out any old files by using the menu to "Build/Clean Project"" \ No newline at end of file +**Don’t:** +- Don’t push commits directly to `master`. +- Don’t leave unfinished work on `master`. +- Don’t mix unrelated changes in one branch. + +--- + +## 7. Example Workflow + +```bash +# Get latest code +git checkout master +git fetch upstream +git merge upstream/master +git push origin master + +# Start a new feature +git checkout -b feature/teleop-improvements + +# Work on code, then commit +git add . +git commit -m "improved joystick scaling in TeleOp" + +# Push branch +git push origin feature/teleop-improvements +```