E-CAM example module
This is an example of what a module for E-CAM looks like. The original source of this page (readme.rst)
contains lots of additional comments to help you create your module (and understand ReST syntax) so please use this as
a starting point. You are free add any level of complexity you wish (within the bounds of what ReST can do). More
general instructions for making your contribution can be found in “How to contribute?”.
Remember that for a module to be accepted into the E-CAM repository, your source code changes in the target application
must pass a number of acceptance criteria:
- Style (use meaningful variable names, no global variables,…)
- Source code documentation (each function should be documented with each argument explained)
- Tests (everything you add should have either unit or regression tests)
- Performance (If what you introduce has a significant computational load you should make some performance optimisation
effort using an appropriate tool. You should be able to verify that your changes have not introduced unexpected
performance penalties, are threadsafe if needed,…)
Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how
it fits into the larger picture of what you want to achieve.
If needed you can include latex mathematics like
which won’t show up on GitLab/GitHub but will in final online documentation.
If you want to add a citation, such as [CIT2009]. Note that citations may get rearranged, e.g., to the bottom of the
“page”.
| [CIT2009] | A citation (as often used in journals). |
Provide the build information for the module here and explain how tests are run. This needs to be adequately detailed,
explaining if necessary any deviations from the normal build procedure of the application (and links to information
about the normal build process needs to be provided).
Here link the source code that was created for the module. If you are using Github or GitLab and the Gitflow Workflow you can point to your feature branch.
Linking to your pull/merge requests is even better. Otherwise you can link to the explicit commits. In this example I’m
using a patch file to highlight my source code changes, for that reason I need to explain what code (including exact
version information), the source code is for.
You can create a similar patch file by (for example if you are using git for your version control) making your changes
for the module in a feature branch and then doing something like the following:
[adam@mbp2600 example (master)]$ git checkout -b tmpsquash
Switched to a new branch "tmpsquash"
[adam@mbp2600 example (tmpsquash)]$ git merge --squash newlines
Updating 4d2de39..b6768b2
Fast forward
Squash commit -- not updating HEAD
test.txt | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git commit -a -m "My squashed commits"
[tmpsquash]: created 75b0a89: "My squashed commits"
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git format-patch master
0001-My-squashed-commits.patch
To include a patch file do something like the following (take a look at the source code of this document to see the
syntax required to get this):
| Always remember that a good patch file should have a comment inside about what the patch is for....just like this
--- hello.c 2014-10-07 18:17:49.000000000 +0530
+++ hello_new.c 2014-10-07 18:17:54.000000000 +0530
@@ -1,5 +1,6 @@
#include <stdio.h>
-int main() {
+int main(int argc, char *argv[]) {
printf("Hello World\n");
+ return 0;
}
|
If the patch is very long you will probably want to add it as a subpage which can be done as follows
you can reference it with Patch file for module
