Moved fuzz dir to test/fuzz

Extended contributing document to testing and licensing

CONTRIBUTING.md

@@ -1,23 +1,13 @@
-## Documentation
+# Contributing clixon code
 
-How to document the code::
+The clixon project welcomes contributions from the community.
 
-  /*! This is a small comment on one line
+A contribution must follow the [CLIXON
-   *
+licensing](https://github.com/clicon/clixon/blob/master/LICENSE.md)
-   * This is a detailed description
+following the dual licensing: either Apache License, Version 2.0 or
-   * spanning several lines.
+GNU General Public License Version 3.
-   *
+
-   * Example usage:
+#A CLA such as generated by eg https://contributoragreements.org may need to be signed.
-   * @code
-   *   fn(a, &b);
-   * @endcode
-   *
-   * @param[in] src         This is a description of the first parameter
-   * @param[in,out] dest    This is a description of the second parameter
-   * @retval TRUE           This is a description of the return value
-   * @retval FALSE          This is a description of another return value
-   * @see                   See also this function
-   */
 
 ## C style
 
@@ -25,8 +15,8 @@ Clixon uses 4-char indentation, a la emacs "cc-mode".
 
 ### Function declarations
 
-Functions in C code are written as follows::
+Functions in C code are written as follows:
-
+```
   static int
   myfn(int           par1,
        my_structure *par2)
@@ -35,30 +25,32 @@ Functions in C code are written as follows::
       my_structure *ms;
 
       ms = NULL;
+```
 
 Notes:
 
-1. the return type of the function and all qualifers on first line (`static int`)
+1. The return type of the function and all qualifers on first line (`static int`)
-2. function name and first parameter on second line, thereafter each parameter on own line
+2. Function name and first parameter on second line, thereafter each parameter on own line
 3. Each parameter indented to match the "longest" (`my_structure`)
 4. Pointer declarations written: `type *p`, not: `type* p`.
 5. All local variables in a function declared at top of function, not inline with C-statements.
 6. Local variables can be initialized with scalars or constants, not eg malloc or functions with return values that need to be  checked for errors
 7. There is a single empty line between local variable declarations and the first function statement.
 
-
+Function signatures are declared in include files or in forward declaration using "one-line" syntax, unless very long:
-Function signatures are declared in include files or in forward declaration using "one-line" syntax, unless very long::
+```
-
   static int myfn(int par1, my_structure *par2);
+```
 
 ### Errors
 
-Errors are typically declared as follows::
+Errors are typically declared as follows:
-
+```
     if (myfn(0) < 0){
        clicon_err(OE_UNIX, EINVAL, "myfn");
        goto done;
     }
+```
 
 All function returns that have return values must be checked
 
@@ -70,7 +62,7 @@ Default return values form a function are:
 In some cases, Clixon uses three-value returns as follows:
 
 - `1`  OK
-- `0`  Invalid
+- `0`  Invalid (and usually a cxobj* return value)
 - `-1` Fatal error
 
 ### Return values
@@ -95,4 +87,35 @@ Notes:
 
 Use `/* */`. Use `//` only for temporal comments.
 
-Do not use "======", ">>>>>" or "<<<<<<" in comments since git merge conflict uses that.
+Do not use `======`, `>>>>>` or `<<<<<<` in comments since git merge conflict uses that.
+
+## Documentation
+
+How to document the code:
+```
+  /*! This is a small comment on one line
+   *
+   * This is a detailed description
+   * spanning several lines.
+   *
+   * Example usage:
+   * @code
+   *   fn(a, &b);
+   * @endcode
+   *
+   * @param[in]     src     This is a description of the first parameter
+   * @param[in,out] dest    This is a description of the second parameter
+   * @retval        0       This is a description of the return value
+   * @retval       -1       This is a description of another return value
+   * @see                   See also this function
+   */
+```
+
+## Testing
+
+For a new feature, you need to write [a CI test](https://github.com/clicon/clixon/blob/master/test/README.md), including some functionality tests and preferably some negative tests. Tests are then run automatically as regression on commit [by github actions](https://github.com/clicon/clixon/actions/).
+
+These tests are also the basis for more extensive CI tests run by the project which
+include [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test), [vagrant tests on other platforms](https://github.com/clicon/clixon/tree/master/test/vagrantvalgrind), [coverage tests](https://app.codecov.io/gh/clicon/clixon) and occasional [fuzzing with AFL](https://github.com/clicon/clixon/tree/master/fuzz).
+
+In particular, a new feature must pass the [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test).

LICENSE.md

@@ -1,5 +1,7 @@
 Copyright (C) 2009-2016 Olof Hagsand and Benny Holmgren
+
 Copyright (C) 2017-2019 Olof Hagsand
+
 Copyright (C) 2020-2021 Olof Hagsand and Rubicon Communications, LLC (Netgate)
 
 CLIXON is dual license. 

README.md

@@ -13,7 +13,7 @@ See [documentation](https://clixon-docs.readthedocs.io), [project page](https://
 Clixon is open-source and dual licensed. Either Apache License, Version 2.0 or GNU
 General Public License Version 2; you choose, see [LICENSE.md](LICENSE.md).
 
-Latest release is 5.3.0 released in September 2021. See [CHANGELOG.md](CHANGELOG.md) release history.
+Latest release is 5.3.0 from September 2021. See [CHANGELOG.md](CHANGELOG.md) release history.
 
 Clixon interaction is best done posting issues, pull requests, or joining the
 [slack channel](https://clixondev.slack.com).

apps/backend/clixon_backend_plugin.h

@@ -75,10 +75,12 @@ typedef struct {
  * state (such as a cache) and can expect more pagination calls until the running db-lock is 
  * released, (see ca_lockdb)
  * The transaction is the regular lock/unlock db of running-db of a specific session.
- * @param[in]  locked     "running" datastore is locked by this caller
  * @param[in]  offset     Offset, for list pagination
  * @param[in]  limit      Limit, for list pagination
- * see also pagination_data in clixon_plugin.h
+ * @param[in]  locked     "running" datastore is locked by this caller
+ * @param[out] xstate     Returned xml data state tree
+ * @see pagination_data in clixon_plugin.h
+ * @see pagination_offset() and other accessor functions
 */
 typedef struct {
     uint32_t          pd_offset;    /* Start of pagination interval */

apps/backend/clixon_backend_transaction.h

@@ -67,9 +67,9 @@ int transaction_log(clicon_handle h, transaction_data th, int level, const char
 /* Pagination callbacks
  * @see pagination_data_t  internal structure
  */
-int      pagination_locked(pagination_data pd); 
 uint32_t pagination_offset(pagination_data pd); 
 uint32_t pagination_limit(pagination_data pd); 
+int      pagination_locked(pagination_data pd); 
 cxobj   *pagination_xstate(pagination_data pd); 
 
 #endif /* _CLIXON_BACKEND_TRANSACTION_H_ */

lib/clixon/clixon_plugin.h

@@ -207,7 +207,8 @@ typedef int (plgreset_t)(clicon_handle h, const char *db);
 typedef int (plgstatedata_t)(clicon_handle h, cvec *nsc, char *xpath, cxobj *xtop);
 
 /* Pagination-data type
- * @see pagination_data_t in clixon_backend_transaction.h for full pagination API 
+ * @see pagination_data_t in for full pagination data structure
+ * @see pagination_offset() and other accessor functions
  */
 typedef void *pagination_data;