Onboarding
This page will help you learn everything you need to get started. We will go over the programs we use and how you can get access, the general software structure including how to contribute and how to access all our data, and our current approach to project management. Please read through this carefully, do all the steps, and have a skim through this whole wiki. When onboarding, Alex Thoms will set you up with access to everything you need. You can reach him on slack or via email at adthoms@ucla.edu.
Everything related to our research (with the exception of code) is stored in a shared UCLA google drive folder. Please see the readme for file naming and storage conventions. To keep this folder organized, these conventions must be followed. UCLA staff/student's have unlimited upload storage, with guest uploads limited to their personal storage. According to IT, this should not be the case, though a fix has not yet surfaced.
Slack is used for all internal communication. Channels are created on a per-project basis, with other channels serving admin or general purposes. For UCLA students, we highly recommend using your official UCLA email (i.e. @ucla.edu) for your MyUCLA account, as this seems to work best with UCLA's enterprise version of Slack, which we use.
Asana is used for project management (instead of Trello and other products) as it currently offers the most features for free. Since our lab is relatively small, project leads may choose to use Asana though sometimes its best to hold meetings and keep track of things on paper.
Matlab 2020a or later is required with the following toolboxes. Though Matlab is only required for a small component of our calibration procedure, we recommend installing all toolboxes as these come in handy for course work and/or software prototyping. All UCLA staff/students are eligable for a free license. For ease of use, we recommend installing MATLAB on Windows, as installing MATLAB on ubuntu requires root access and is rather cumbersome to develop in.
As a legacy to the SDIC lab at the University of Waterloo, we maintain communication for legacy projects on Microsoft Teams. Any project started at UCLA is maintained on Slack, with uWaterloo students added as guests.
We use Github for all code management. Before contributing, please read through the follow subsections:
Organization of Repositories
- Our core repositories are contained within the beam_robotics repository. This repository follows a monorepo structure, and all software developed within our stack must remain compatible with it.
- Make sure you are familiar with submodules before working with beam_robotics (See tut. 1, 2)
- The beam_robotics repo also contains this Wiki. All instructions for lab workflows should be in this wiki and not in any other repository's wiki.
- There are instructions for installing beam_robotics on development machines and beam robots here
Task Management with Github
- Github issues are used for task management / project management.
- These issues are coding specific and should be do-able within one day to one month. If any one task takes longer than one month, it should be divided into sub-tasks and added to Asana.
- Each task should be tracked as follows:
- Create a new issue for the repo you are editing. This issue should start with an appropriate label from those currently available
- Open a new branch for each issue you are working on.
- The branch should be named similar to your task and should start with add_ or fix_ (e.g., fix_transform_bug)
- You can commit as much as you want to this branch
- Create pull request to merge this branch to main
- Only merge this branch to main once you have completed the issue and performed testing (see testing section)
- All merges to main branches should be done by issuing a pull request
- The pull request must be reviewed by at least one person, so please assign someone you think is capable of reviewing the pull request
- Merge the branch
- The reviewer will review the code, but it is up to the person who made the changes to merge the branch once reviewed
- As these branches follow the feature branch paradigm, we recommend to squash and merge the branch into main
- Once the branch has been merged, delete the branch and close the issue
Testing
- Testing is a necessary component of software development
- Testing should be performed as much as possible while writing your code
- Some code is hard to test (e.g., integration tests and system tests), so not all things need to be tested. However, any existing repositories with tests must be maintained and extended when new features are added. This is particularly true for libbeam as this is our publicly released library upon which all of our software depends. Newly developed repositories should also contain tests.
- In libbeam, Catch2 is used for testing, though for newer projects we use gtest as it has nice ROS integration.
- C++ writing guidelines
- Code formatting
- If you need to learn ROS, see ROS Tutorials
- 3D geometry notation guidelines