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.
|
```bash
|
||||||
To locate these samples, find the FtcRobotController module in the "Project/Android" tab.
|
git clone https://github.com/KeshavAnandCode/DecodeFTCMain.git
|
||||||
|
cd DecodeFTCMain
|
||||||
|
```
|
||||||
|
|
||||||
Expand the following tree elements:
|
4. Verify your remotes:
|
||||||
FtcRobotController/java/org.firstinspires.ftc.robotcontroller/external/samples
|
|
||||||
|
|
||||||
### Naming of Samples
|
```bash
|
||||||
|
git remote -v
|
||||||
|
```
|
||||||
|
|
||||||
To gain a better understanding of how the samples are organized, and how to interpret the
|
You should see:
|
||||||
naming system, it will help to understand the conventions that were used during their creation.
|
```
|
||||||
|
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.
|
## 2. Keeping `master` Clean
|
||||||
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
|
- `master` should only contain clean, tested code.
|
||||||
of a particular style of OpMode. These are bare bones examples.
|
- 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.
|
```bash
|
||||||
It is not intended to drive a functioning robot, it is simply showing the minimal code
|
git checkout master
|
||||||
required to read and display the sensor values.
|
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.
|
## 3. Creating a Feature Branch
|
||||||
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:
|
Whenever you start a new task (feature, fix, experiment):
|
||||||
|
|
||||||
* Sensor class names are constructed as: Sensor - Company - Type
|
1. Update `master` (see above).
|
||||||
* Robot class names are constructed as: Robot - Mode - Action - OpModetype
|
2. Create a new branch from `master`:
|
||||||
* 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
|
```bash
|
||||||
basis for your own robot. In all cases, the desired sample(s) needs to be copied into
|
git checkout master
|
||||||
your TeamCode module to be used.
|
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.
|
Branches **must** follow the format:
|
||||||
|
|
||||||
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")
|
<type>/<short-description>
|
||||||
@Disabled
|
|
||||||
```
|
```
|
||||||
|
|
||||||
The name that will appear on the driver station's "opmode list" is defined by the code:
|
Where `<type>` is one of:
|
||||||
``name="Template: Linear OpMode"``
|
- `feature/` → new functionality
|
||||||
You can change what appears between the quotes to better describe your opmode.
|
- `fix/` → bug fixes
|
||||||
The "group=" portion of the code can be used to help organize your list of OpModes.
|
- `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
|
Examples:
|
||||||
``@Disabled`` annotation which has been included.
|
- `feature/autonomous-path`
|
||||||
This line can simply be deleted , or commented out, to make the OpMode visible.
|
- `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
|
- Make changes in Android Studio.
|
||||||
a common code organization, with each being able to *see* the others code but each having
|
- Stage and commit your changes:
|
||||||
their own team module with their own code that they maintain themselves.
|
|
||||||
|
|
||||||
In this situation, you might wish to clone the TeamCode module, once for each of these teams.
|
```bash
|
||||||
Each of the clones would then appear along side each other in the Android Studio module list,
|
git add .
|
||||||
together with the FtcRobotController module (and the original TeamCode module).
|
git commit -m "short message about what changed"
|
||||||
|
```
|
||||||
|
|
||||||
Selective Team phones can then be programmed by selecting the desired Module from the pulldown list
|
- Push your branch to GitHub:
|
||||||
prior to clicking to the green Run arrow.
|
|
||||||
|
|
||||||
Warning: This is not for the inexperienced Software developer.
|
```bash
|
||||||
You will need to be comfortable with File manipulations and managing Android Studio Modules.
|
git push origin feature/short-description
|
||||||
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 :)
|
|
||||||
|
|
||||||
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"
|
- Once your branch is ready:
|
||||||
folder to a sibling folder with a corresponding new name, eg: "Team0417".
|
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
|
## 6. Branching Rules
|
||||||
to a matching name with a lowercase 'team' eg: "team0417".
|
|
||||||
|
|
||||||
4) In the new Team0417/src/main folder, edit the "AndroidManifest.xml" file, change the line that contains
|
**Do:**
|
||||||
package="org.firstinspires.ftc.teamcode"
|
- Always branch from `master`.
|
||||||
to be
|
- Follow the naming standard exactly.
|
||||||
package="org.firstinspires.ftc.team0417"
|
- Keep branches small and focused.
|
||||||
|
- Delete branches after they’re merged.
|
||||||
|
|
||||||
5) Add: include ':Team0417' to the "/settings.gradle" file.
|
**Don’t:**
|
||||||
|
- Don’t push commits directly to `master`.
|
||||||
6) Open up Android Studios and clean out any old files by using the menu to "Build/Clean Project""
|
- 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