This is the official Github for team Kanaloa. Our main website can be found here.
Do not commit edits to the Master branch until they have been fully vetted in hardware! And approved by Dr. Trimble or the appropriate graduate student mentor.
Documentation: tutorials, primer documents, and detailed notes on specific topics.Projects: files related to a specific project or event.SurfaceVehicles: files related to the operation of a specific surface vehicle.
All directories shall start with a capital letter. Utilize camel case for multiple words (capitalize the first letter of subsequent words with no spaces; you may use underscores _, but do so sparingly). Example: SampleDirectory.
- For files requiring manual version control, the filenames shall start with the date that file was originally created. This is in the format
YYYYMMDD_name.namemust start with a lowercase letter. Utilize camel case for multiple words capitalize the first letter of subsequent words with no spaces; you may use underscores_, but do so sparingly). Example:20180101_sampleFilename.extension. Examples of files that require manual version control include: code reflecting major hardware revisions, notes, work in progress, etc. You will need to use your judgement when deciding which files need manual version control. Github automatically handles version control by nature; however, it makes sense for manual version control in some cases. - For files that do not require manual version control, follow the same naming convention as above, omitting the date and underscore. Example:
sampleFilename.extension.
Exceptions:
- Matlab (in Linux) dislikes filenames that start with numbers. For this reason, Matlab script
.mfilenames should begin with the letterm. Other than this, the naming convention remains the same. Example:m20180101_sampleMatlabFilename.m - Arduino IDE (in Linux) dislikes filenames that start with numbers. It also prefers that .ino scrips sit inside a directory with the same name as the filename. For this reason, Arduino script
.inofilenames should begin with the letter a. The script should sit inside a directory named identical to the filename. Other than this, the naming convention remains the same. Example:.../a20180101_sampleArduinoFilename/a20180101_sampleArduinoFilename.ino
For writing tutorials and/or primer dicuments in Git, put the document in its own directory. Name the directory a properly descriptive name (e.g. "InstallationInstructions", "PackageLists", "WritingAPackage", etc.), then name the document inside the directory README.md. This will allow you to leverage Git's built-in writing and formatting syntax, which will allow you to write nicely-formatted documents like the one you are reading right now!
Branches are used to create an instance of the Master branch. This feature allows you to make enhancements, fix bugs, or try out new ideas without messing up the existing working files. Whenever working on code, work should be done on a separate branch to help avoid merge conflicts or buggy code from being in master branch. The master branch should contain only the most up-to-date working files. At all times the master branch must be fully operaable and ready to load to a vehicle. We recommend getting familiar with GitHub Desktop so that you can see which branch you are working on and will be making commits to.
Your branch name should be short but also descriptive. For example, when updating this Standard Operating Procedure (SOP), the branch name is update-github-sop. The only work being done in this branch is work related to this SOP (README.md).
First, make sure you are on the main page and master branch. You create a branch off the currently select branch. If you are not on master you could end up merging non-working code down the line. Click where it says master and enter your branch name in the text field. Then click on Create branch: branch-name from 'master'.
Alternative Ways:
On GitHub Desktop, make sure that you have cloned the repository. Once cloned, you should see Kanaloa as the Current repository and Current branch as master. Switch the Current branch to the branch that you will be working on.
Note: If you accidentally started work on a different branch, you can switch branches and bring all changes over.
Before merging, make sure that your branch is up to your latest code. Now, on the main page, switch to the branch that you are working on. Click on Pull request and you should see:
base:master <- compare:branch-name Able to merge. These branches can be automatically merged.
The title will be automatically filled out with your last commit to the branch. Update this to highlight the overall issue that you were handling. On the right-hand side, fill out the fields similar to Section 4.2.
If there is a conflict, you can review the code to see where it is happening. Due to multiple members working on the same repository, there are chance of them happening. Here is the documentation on how to resolve it.
To view the version history of a file, click on the file's name then History on the top right. This feature allows you to see all commits that affected this file as well as view the version the file was during the time of that commit. You can also bring back the repository to that current state of time if you are looking at various files within the repository.
It is useful for:
- Tracking changes to code line-by-line
- Especially useful when tracking down problems
- Finding out who made the commit
- Knowing the author of the code will allow you to understand their thought proccess when making the code
Action items are currently being tracked using this Google Sheets.
Please note that this spreadsheet is restricted to those in the Kanaloa Google Drive. If you are a member and do not have access, please contact Dr. Trimble or a graduate student for further assistance.
- GitHub Desktop (this is a great UI for those starting to learn GitHub)
- GitHub Documentation
- GitHub CLI (for more advanced users and/or cases)