Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
doc:guidelines [2019/02/14 18:23] – [Collaborative Development] gkazhoya | doc:guidelines [2019/05/16 13:34] – Added a bit of info on copyright notices. gkazhoya |
---|
==== Development of Roslisp Packages ==== | ==== Development of Roslisp Packages ==== |
| |
**package.xml/manifest.xml** | **package.xml** |
| |
Relevant documentation: [[http://www.ros.org/reps/rep-0127.html|Package.xml Ref]] | Relevant documentation: [[http://www.ros.org/reps/rep-0127.html|Package.xml Ref]] |
| |
* No manifest.xml's :) If you create a new package, please stick to //catkin// | * As a ''<build_depend>'' only specify all the rosdep keys or ROS packages that your package requires at build-time, e.g. other ROS package sources, library headers. Whereas, ''<run_depend>'' is for rosdep keys and ROS packages that your package needs at run-time, e.g. shared libraries, executables, Python modules, launch scripts. More documentation for this can be found [[http://wiki.ros.org/catkin/conceptual_overview#Dependency_Management|here]]. |
* As a ''<build_depend>'' only specify all the rosdep keys or ROS packages that your package requires at build-time, e.g. other ROS package sources, library headers. Whereas, ''<run_depend>'' is for rosdep keys and ROS packages that your package needs at run-time, e.g. shared libraries, executables, Python modules, launch scripts. \\ For example, you should put ''sbcl'' as a build dependency for all your Lisp packages. Although we don't explicitly use ''sbcl'' when ''catkin_make''-ing our Roslisp packages, you will still need ''sbcl'' in the next step of your compilation process (inside emacs slime). For all packages where ''sbcl'' is a build dep, it will be automatically ''sudo apt-get install''-ed by ''rosdep'' when you first cloned the source code of that package and ran ''rosdep'' on it. On the other hand, you actually don't need a Common Lisp compiler during the execution of your compiled Lisp ''*.fasl'' executives, so I guess you don't need ''sbcl'' as a run dep (is this actually correct?)... A good example of this is: ''<build_depend>libsomelib1.6-dev</build_depend>'', whereas ''<run_depend>libsomelib1.6</run_depend>''. More documentation for this can be found [[http://wiki.ros.org/catkin/conceptual_overview#Dependency_Management|here]]. | |
* Use ''<export><deprecated /></export>'' to tag deprecated packages | * Use ''<export><deprecated /></export>'' to tag deprecated packages |
* The license for all CRAM code should be BSD / Public Domain | * The license for all CRAM code should be BSD / Public Domain |
**Lisp** | **Lisp** |
| |
* Pay attention to the indentation! :D | * Pay attention to the indentation!!! |
* Try not to exceed 80 symbols in width in your code | * Try not to exceed 80 symbols in width in your code |
* Lisp names (variables, classes, methods, packages) are all lowercase with dashes in between: my-awesome-lisp-variable | * Lisp names (variables, classes, methods, packages) are all lowercase with dashes in between: ''my-awesome-lisp-variable'' |
* Do you usually get that feeling that something is underdocumented? :) Think about that when writing your own code. (not that the author of this guideline always sticks to this particular rule, unfortunately...) | * Do you usually get that feeling that something is underdocumented? :) Think about that when writing your own code. (not that the author of this guideline always sticks to this particular rule, unfortunately...) |
| * Try not to ''use'' too many packages in your ''package.lisp''. Instead, specify package namespaces explicitly in your code, e.g. ''cl-transforms:x'' instead of ''x''. That way code is more readable. |
| * Don't use ''cl-tf'' if you actually want ''cl-transforms''. The difference is: |
| * ''cl-transforms'' defines datatypes such as ''pose'' and ''transform'' and their utility functions, such as ''angle-between-quaternions''. |
| * ''cl-transforms-stamped'' defines datatypes of ''pose-stamped'' and ''transforms-stamped''. So once you need a frame header, use ''cl-transforms-stamped''. |
| * ''cl-tf'' defines the transform listener library, so if you need to do ''lookup-transform'', use ''cl-tf''. |
| * ''cl-tf2'' is the equivalent of ''cl-tf'' only with an alternative implementation based on the ''buffer_server'' from ''tf2_ros'' package. |
| |
**Ros-related** | **Ros-related** |
| |
* ROS packages' names are usually lowercase with underscores in between: my_awesome_ros_package | * ROS packages' names are usually lowercase with underscores in between: ''my_awesome_ros_package''. |
| |
| |
| ==== Copyright notices ==== |
| CRAM is open source software licensed under the BSD licence. |
| This means the code can be used by any third party without having to contribute anything back and having to mention the original authors. |
| Our copyright notice is there to allow others to use our software without being afraid of being sued. |
| |
| An example copyright notice can be found in the header of most ''*.lisp'' files in CRAM. |
| |
| Here are some guidelines on how to deal with the copyright notice of your code: |
| * When you create a new ''*.lisp'' or ''*.asd'' file or any other source code file, please add a copyright notice with your name and institution name. |
| * If you simply copy pasted a file, please keep the original notice intact. |
| * For non-sourcecode files such as a ''package.xml'' file, make sure to simply put your name in the correct tag (e.g. ''<author>''). |
| * When editing an existing file, you can add your name into the header if you made a substantial contribution to the code. |
| |
| A contribution is considered substantial if: |
| * you added a new feature, |
| * you fixed a major bug and thereby edited many lines of code in the file. |
| |
| A contribution is considered not substantial if: |
| * you fixed a typo, |
| * fixed indentation, |
| * slightly improved a documentation string, |
| * other minor contributions such as minor refactoring and nicification, |
| * minor bug fixes, |
| * copy paste of existing code with minor tweaks. |
| |
| |