Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
doc:guidelines [2015/04/28 15:27] – [Development of Roslisp Packages] gkazhoyadoc:guidelines [2019/07/11 13:24] (current) – gkazhoya
Line 7: Line 7:
   * Always use the GIT version control system when developing   * Always use the GIT version control system when developing
   * One commit per feature with a meaningful commit message   * One commit per feature with a meaningful commit message
 +  * Use square brackets to annotate for which package the commit is. E.g.: ''"[btr] new feature for btr package"''
   * Send a //pull request// through GitHub, when:   * Send a //pull request// through GitHub, when:
     * you want somebody to review your code     * you want somebody to review your code
Line 16: Line 17:
 ==== 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
Line 35: Line 35:
 **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 the rules herself hmm...)+  * 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''.
  
  
-==== Lisp Programming ==== +==== Copyright notices ==== 
-Some Lisp patterns and stuff would be nice, like tail recursive functions and optimization flags, making sure the functions have no side effects, etcetc...+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.
  
-==== Testing ====+An example copyright notice can be found in the header of most ''*.lisp'' files in CRAM.
  
-The preferred Lisp package for writing simple unit tests is [[http://common-lisp.net/project/lisp-unit|lisp-unit]].+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.
  
-**Running existing tests**+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, 
 +  * you made a major refactoring of the code and improved readability and maintainability greatly.
  
-Just do+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.
  
-<code>,r-l-s ROS_SYSTEM_TO_TEST asdf-system-to-test-tests</code>+This definition is, of course, not quantitative. If you are unsure, ask the current main maintainer of the software for an advice or look on the Internet for some inspiration, e.g., from the [[https://www.gnu.org/prep/maintain/html_node/Copyright-Notices.html#Copyright-Notices|GNU project]].
  
-The asdf system for tests usually has either the ''-tests'' suffix, or ''-test'' suffix. 
  
-And then:+==== Unit Testing ====
  
-<code> +Testing your code is essential! 
-,!p asdf-system-to-test-tests +CRAM is a huge framework with a thousands of lines of code, so we have to make sure that whatever bricks we put in our CRAM skyscraper, they are robust. A couple of fragile bricks and our whole building will collapse.
-(run-tests) +
-</code> +
-or +
-<code> +
-... +
-(run-tests my-define-tests-function-name) +
-</code>+
  
-That's all.+To aid with testing, consider adding unit tests to functions in your code that have math and to your main API functions. 
 +Take a look at the [[http://cram-system.org/tutorials/beginner/testing|testing tutorial]] to get started on writing tests.
  
-**Writing unit tests for your functions** 
  
-TODO: here should go a link with some testing tutorial+==== Lisp Programming ==== 
 +Todo: Some Lisp patterns and stuff would be nice, like tail recursive functions and optimization flags, making sure the functions have no side effects, etcetc...
  
-**FiveAM** 
-If lisp-unit isn't expressive enough for you, consider using [[http://common-lisp.net/project/fiveam/|FiveAM]]. 
-To run tests written with FiveAM (1) load the tests asdf package, (2) change to the corresponding Lisp package in the REPL and (3) execute ''(run!)''. If ''(run!)'' doesn't do anything automatically, try specifying the test suite name: ''(run! 'MY_TEST_SUITE_NAME)''. You can find the name by ''rgrep''-ing ''(def-suite'' in your ASDF package.