diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..cf7c817 --- /dev/null +++ b/404.html @@ -0,0 +1,472 @@ + + + +
+ + + + + + + + + + + + + + +Your best friend when writing software. Git is a distributed version control +system that allows multiple developers to track changes, collaborate, +and manage code history efficiently.
+The use of Git should be your number one tool if you do any type of software development. +If you are reading this guide, the chances that you already are in our GitHub organization +are high. In case you did not know, any software that you work on, whether already existing +or new should all be hosted on our organization.
+In order to maintain a good consistency across all repositories in our organization, +some conventions are encouraged to be followed. The conventions not only help you +to manage your development, such as finding where things were added, fixed or even +roll back to a working state are one the main key advantages. In addition, by following +these conventions, you will be helping others as well and make use of automated tools +to generate good CHANGELOGs for instance.
+_ws
suffix. Such an example is the tello_ws..gitignore
file. You can use a generator hereEach repository should have at least 2 branches: main
/master
and a dev
.
+The main
should always contain a stable version of software and the dev
should
+be the development branch, where all new changes are performed.
When you are about to start the implementation of a new feature, and/or fixing a bug,
+you should create a new branch where it will have the new feature, or the fix.
+Therefore, you should create the branch from the dev
branch. For this reason,
+each new branch should have a prefix followed by /details_of_change
. Here are some examples:
feat/add-login-page
: This branch name indicates that the work being done involves adding a login page feature.
fix/typo-in-header
: This branch name suggests that the focus is on fixing a typo found in the header section of the project.
refactor/restructure-database
: This branch name indicates that the work involves refactoring or restructuring the database architecture.
docs/update-readme
: This branch name suggests updating the project's README documentation.
test/add-unit-tests
: This branch name indicates adding unit tests to the project for testing purposes.
style/change-button-color
: This branch name suggests changing the color of buttons in the user interface.
hotfix/fix-security-vulnerability
: This branch name indicates a critical fix for a security vulnerability.
chore/clean-up-unused-code
: This branch name suggests cleaning up unused code or files in the project.
Once a branch has fulfilled its purpose, a new pull request (PR) should be created, and
+assigned to another team member who will be responsible for reviewing the code and merging it into the dev
branch.
Hint
+Once the dev
branch is stable, the same should be merged to the main
branch by creating a PR.
Commits should be well-scoped and frequent. Each commit message should reflect on a change that +has been performed, where the message should be short and straight to the point. In case some +more details are needed, you can make use of the body of the message to write more details.
+Here is how a commit message should be structured:
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+
The types of commits can be: feat
, fix
, chore
...
Info
+For more details and why you should use convey to using this convention can be found here
+All repository created should be set to private. This is because you do not own your repository but in fact it's the University of Luxembourg. Nevertheless, that does not mean you cannot make it open-source. If you want to make it open-source please have a discussion with Holger or Jose-Luis.
+In case you desire to make your project open-source, your repository should have +a license. This license is usually selected by the TTO (Technology Transfer Office) , after a full investigation +of your repo, to see if it passes all checks.
+Nevertheless, you could already create a license file when creating the repo. +The license that will be applied will most likely be GPL-3.0.
+In our team, which focuses on robotics, the use of ROS should be highly encourage, +if not mandatory. This not only will make sure that your work will be able to be +tested on real platforms, but also streamline your work due to the amount of +projects that will help evolve faster.
+Follow this guide if you are going to create a ROS package. It will help you follow +the ROS standards, and maintain consistency across all our repositories. +In addition, the guide streamlines the process of publishing it to the ROS index, +as well as having a consistent pattern throughout our team.
+There are 2 version available at the moment of writing this guide, ROS1 and ROS2. +If you are about to start now, please use ROS2, choosing the distribution that +is the LTS version. Currently, this is humble.
+Warning
+Please try to avoid ROS1. This is because ROS1 will reach end-of-life soon.
+Note
+Before starting a new project, you should get familiar with our git conventions.
+In order to create a new project, you should go to the organization and press the +new button, as shown in the picture bellow: +
+Then, you should name your repository as well as toggle some checkboxes as shown in the picture bellow, +highlighted in green:
+Info
+Make sure to select snt-arg
as the owner and not yourself!
There are several ways one could do that. The most common and the suggested way,
+is to make use of the tool vcstool. You should create a
+file .rosinstall
. This file should look something like this:
repositories: # The file needs to start with this line!
+ s_graphs_utils/fast_gicp: # Path to where the package should be located
+ type: git # This most likely should not change
+ url: https://github.com/SMRT-AIST/fast_gicp.git # The package git https
+ version: master # Branch name of the package repository
+ # Another package...
+
For an example file, you can refer to unitree_ws.
+In case you will create more that one package, say a message package for you package, +there are 2 possible ways.
+The first one is to have them both on the repo. The structure should be like this:
+package_name_root
+ - package_name
+ - package_name_msgs
+ - another package
+ - README.md
+ - .rosinstall
+ - .gitignore
+ - ...
+
The second option is to create a separate repository and then including it in the
+.rosinstall
.
Note
+You should avoid adding them as submodules. This will complicate things in +case you desire to push your package to ROS index.
+Workspaces are needed when you plan on using your package in a real or virtual platform. +This means that you package will no longer be a standalone package, but will work with +other packages. For instance, you will need a driver for the robot or for a lidar.
+That's when a workspace will come in handy.
+To create a workspace, proceed to create a new repo, where the name should be of the
+form <project_name>_ws
. This repo should not directly include any package. Instead,
+it should include scripts to setup the workspace, by getting the necessary packages,
+having docker files to build docker images etc. This means that you should still use
+vcstool for managing workspace repositories.
Below are some files you might consider having. For a full fledged workspace, consider +having a look at tello_ws or unitree_ws.
+ |- .gitignore
+ |- .rosinstall
+ |- requirements.txt
+ |- Dockerfile
+ |- README.md
+ |- setup.sh
+
The .rosinstall
file points to one or more ROS package repositories that are
+required by the project, and is used by vcstool
to fetch these dependencies.
Similarly, the requirements.txt
file should contain a list of required Python
+modules, whereas the Dockerfile
specifies how to build a Docker container for the project.
Finally, setup.sh
is a script that calls automates the setup of the workspace
+e.g., calling vcstool
, pip
, and so on.
Note
+Note that except for the .rosinstall
, all other files are optional.
Warning
+Other directories can be added depending on the requirements of each project, but try to keep the folder structure as compact as possible.
+Below is a description of what should be inside each of these directories.
+/drivers
: This folder contains all packages providing drivers for running both simulations and the real robot. The /drivers
directory can have sub-folders such as /real
and /simulation
, containing packages for executing the real world robot and the robot in simulation, respectively.
/generic
: This folder contains all relevant packages for launching the processes required for successully executing a given task/mission for the project. It can be further divided into /bringup
and /description
. As an example, the 5G_sky_ws
workspace could have both the 5G_sky_bringup
and 5G_sky_description
subdirectories.
/navigation
: This folder contains all packages required for navigation. It can be divided into sub-folders such as /slam
, /localization
, /planning
and /perception
.
/utils
: This folder contains all packages that are required but not available in the form of binaries.
Each project will have a bringup repository and a description repository, these repos will be named as project_bringup and project_description.
+project_bringup : The project_bringup as the name suggests is responsible for bringing up all the processes responsible for proper execution of the robot and its sensors, where it be in a simulated environment or in real world. Basically it has all the launch and config files of the different packages which are grouped together to launch an entire mission of the robot. How to create a bringup repo (example: 5G_sky_bringup
):
cd ~/workspace/ros/5G_sky_ws/src/generic && catkin_create_pkg 5G_sky_bringup roscpp rospy
+cd 5G_sky_bringup && mkdir launch && mkdir config
+
The above command creates a ros repo, it also adds launch
and config
folders. You have to push this created ros repo to github.
project_description : As the name suggests the project description contains the description files the projects. The description file contains the urdfs, meshes, worlds etc for the robots and the environment of the robot.
+cd ~/workspace/ros/5G_sky_ws/src/generic && catkin_create_pkg 5G_sky_description
+cd 5G_sky_description && mkdir launch && mkdir config && mkdir urdf && mkdir worlds
+
The above command will create a ros repo which will have launch
, config
, urdf
and worlds
folders.
You should also clone all the relevant ros packages that do not have binaries and need to installed in the project_ws in the relevant folders. For example if we need a ros package of hdl_graph_slam
inside our 5G_sky_ws
you can clone it inside the folder navigation/SLAM
Once you have all the repos cloned just perform the command below to create a .rosinstall
file which will contain the entire repository management.
cd ~/workspace/ros/5G_sky_ws && touch .rosinstall
+vcs export src > .rosinstall
+git add .rosinstall && git commit -m 'added .rosinstall'
+git push
+
TODO
+ + + + + + + + + + + + + +