Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
doc:guidelines [2013/12/13 15:51] – gkazhoya | doc: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.: ''" | ||
* 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 | ||
* you want your code to be tested on a different machine than yours | * you want your code to be tested on a different machine than yours | ||
- | | + | |
- | * ... | + | |
+ | If you want to introduce major interface changes through you code, make an announcement on the [[https:// | ||
==== Development of Roslisp Packages ==== | ==== Development of Roslisp Packages ==== | ||
- | **package.xml/ | + | **package.xml** |
Relevant documentation: | Relevant documentation: | ||
- | | + | * As a ''< |
- | | + | |
* Use ''< | * Use ''< | ||
- | | + | * The license for all CRAM code should be BSD / Public Domain |
- | | + | |
* Put links to github into the ''< | * Put links to github into the ''< | ||
- | * ... | ||
**my-package-name.asd files** | **my-package-name.asd files** | ||
* Put it into the root of your source directory, no need for symbolic links and asdf directories | * Put it into the root of your source directory, no need for symbolic links and asdf directories | ||
- | * Always explicitly specify dependencies on //all// the Lisp packages, symbols of which you use in your code (even if the dependency is transitive and is automatically added by other packages that you depend on because of hierarchical dependencies) <- is this actually clear? | + | * Always explicitly specify dependencies on //all// the Lisp packages, symbols of which you use in your code (even if the dependency is transitive and is automatically added by other packages that you depend on). |
- | * ... | + | |
Line 38: | Line 35: | ||
**Lisp** | **Lisp** | ||
- | * Pay attention to the indentation! | + | * 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: |
- | * Do you usually get that feeling that something is underdocumented? | + | * Do you usually get that feeling that something is underdocumented? |
- | * ... | + | * Try not to '' |
+ | * Don't use '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
**Ros-related** | **Ros-related** | ||
- | * ROS packages' | + | * ROS packages' |
- | * ... | + | |
- | ==== Testing | + | ==== 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. | ||
- | The preferred Lisp package for writing simple unit tests is [[http:// | + | An example copyright notice can be found in the header of most '' |
- | **Running existing tests** | + | Here are some guidelines on how to deal with the copyright notice of your code: |
+ | | ||
+ | | ||
+ | * For non-sourcecode files such as a '' | ||
+ | * When editing an existing file, you can add your name into the header if you made a substantial contribution to the code. | ||
- | Just do | + | 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. | ||
- | < | + | 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 | ||
- | The asdf system | + | This definition is, of course, not quantitative. If you are unsure, ask the current main maintainer of the software |
- | And then: | ||
- | < | + | ==== Unit Testing ==== |
- | ,!p asdf-system-to-test-tests | + | |
- | (run-tests) | + | |
- | </ | + | |
- | That's all. | + | Testing your code is essential! |
+ | 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. | ||
- | **Writing | + | To aid with testing, consider adding |
+ | Take a look at the [[http:// | ||
- | TODO: here should go a link with some testing tutorial | ||
- | **FiveAM** | + | ==== Lisp Programming ==== |
- | If lisp-unit isn't expressive enough for you, consider using [[http:// | + | Todo: Some Lisp patterns |
- | To run tests written with FiveAM (1) load the tests asdf package, (2) change to the corresponding | + |