changed readme.md for team setup
This commit is contained in:
@@ -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.
|
||||
|
||||
Expand the following tree elements:
|
||||
FtcRobotController/java/org.firstinspires.ftc.robotcontroller/external/samples
|
||||
|
||||
### Naming of Samples
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
Basic: This is a minimally functional OpMode used to illustrate the skeleton/structure
|
||||
of a particular style of OpMode. These are bare bones examples.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
After the prefix, other conventions will apply:
|
||||
|
||||
* 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
|
||||
|
||||
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.
|
||||
|
||||
This is done inside Android Studio directly, using the following steps:
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
@TeleOp(name="Template: Linear OpMode", group="Linear Opmode")
|
||||
@Disabled
|
||||
```bash
|
||||
git clone https://github.com/KeshavAnandCode/DecodeFTCMain.git
|
||||
cd DecodeFTCMain
|
||||
```
|
||||
|
||||
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.
|
||||
4. Verify your remotes:
|
||||
|
||||
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.
|
||||
```bash
|
||||
git remote -v
|
||||
```
|
||||
|
||||
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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ADVANCED Multi-Team App management: Cloning the TeamCode Module
|
||||
## 2. Keeping `master` Clean
|
||||
|
||||
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.
|
||||
- `master` should only contain clean, tested code.
|
||||
- Nobody should ever code directly on `master`.
|
||||
- To stay up to date:
|
||||
|
||||
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 checkout master
|
||||
git fetch upstream
|
||||
git merge upstream/master
|
||||
git push origin master
|
||||
```
|
||||
|
||||
Selective Team phones can then be programmed by selecting the desired Module from the pulldown list
|
||||
prior to clicking to the green Run arrow.
|
||||
---
|
||||
|
||||
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.
|
||||
## 3. Creating a Feature Branch
|
||||
|
||||
Also.. Make a full project backup before you start this :)
|
||||
Whenever you start a new task (feature, fix, experiment):
|
||||
|
||||
To clone TeamCode, do the following:
|
||||
1. Update `master` (see above).
|
||||
2. Create a new branch from `master`:
|
||||
|
||||
Note: Some names start with "Team" and others start with "team". This is intentional.
|
||||
```bash
|
||||
git checkout master
|
||||
git pull origin master
|
||||
git checkout -b feature/short-description
|
||||
```
|
||||
|
||||
1) Using your operating system file management tools, copy the whole "TeamCode"
|
||||
folder to a sibling folder with a corresponding new name, eg: "Team0417".
|
||||
### Branch Naming Standard
|
||||
|
||||
2) In the new Team0417 folder, delete the TeamCode.iml file.
|
||||
Branches **must** follow the format:
|
||||
|
||||
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".
|
||||
```
|
||||
<type>/<short-description>
|
||||
```
|
||||
|
||||
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"
|
||||
Where `<type>` is one of:
|
||||
- `feature/` → new functionality
|
||||
- `fix/` → bug fixes
|
||||
- `experiment/` → prototypes or tests
|
||||
- `docs/` → documentation updates
|
||||
- `chore/` → maintenance or cleanup
|
||||
|
||||
5) Add: include ':Team0417' to the "/settings.gradle" file.
|
||||
Examples:
|
||||
- `feature/autonomous-path`
|
||||
- `fix/motor-init`
|
||||
- `experiment/vision-test`
|
||||
- `docs/setup-instructions`
|
||||
- `chore/gradle-update`
|
||||
|
||||
6) Open up Android Studios and clean out any old files by using the menu to "Build/Clean Project""
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## 4. Working on Your Branch
|
||||
|
||||
- Make changes in Android Studio.
|
||||
- Stage and commit your changes:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "short message about what changed"
|
||||
```
|
||||
|
||||
- Push your branch to GitHub:
|
||||
|
||||
```bash
|
||||
git push origin feature/short-description
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Sharing Your Work
|
||||
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## 6. Branching Rules
|
||||
|
||||
**Do:**
|
||||
- Always branch from `master`.
|
||||
- Follow the naming standard exactly.
|
||||
- Keep branches small and focused.
|
||||
- Delete branches after they’re merged.
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user