Merge pull request #3644 from lawli3t/design-guidelines-2

Add Design guidelines

doc/DESIGN.md

@@ -283,3 +283,41 @@ const Key  *keyGetMeta(const Key *key, const char* metaName);
 The reason behind this is, that the above functions – as their name
 suggest – only retrieve values. The returned value must not be modified
 directly.
+
+## Design Guidelines Checklist
+
+On potential changes of the API/ABI as detected by the
+[`build server`](https://build.libelektra.org/job/libelektra/job/master/),
+please make sure the API has been reviewed according to the
+following 2 checklists:
+
+## Checklist for overall API
+
+### Consistency
+
+- [ ] Consistent naming schemes for enums, macros, typedefs and functions
+- [ ] Same things are named the same and included in [Glossary](/doc/help/elektra-glossary.md)
+- [ ] Different things are named differently
+- [ ] The order of arguments should be consistent across similar functions
+
+### Structural Clarity
+
+- [ ] Functions with similar functionality have the same prefix
+
+### Compatibility
+
+- [ ] All bindings have been updated to reflect the new API and work properly
+
+### Extensibility
+
+- [ ] New API is easily extensible with additional functionality
+- [ ] Components only depend on each other if needed
+
+## Checklist for each function
+
+There are several checklists for functions, depending on the language in which
+the function is written:
+
+- [C](/scripts/api_review/template.c.md)
+- [Rust](/scripts/api_review/template.rs.md)
+- [Java](/scripts/api_review/template.java.md)

doc/api_review/README.md

@@ -0,0 +1,27 @@
+# Elektra API Review
+
+This folder contains all API design reviews conducted on LibElektra.
+Below you can find a short description of the review process.
+
+## Review Process
+
+This review is performed for each function separately. Each function should be
+evaluated according to the checklist. The reviewer judges for every bullet
+point, whether the function does / does not fulfill the bullet point. For
+every unfulfilled point a short explanation has to be given why the reviewer
+thinks the function does not fulfill the respective bullet point. This is done
+simply by providing a short description of the issue below the respective
+bullet point. After the review has been completed, the reviewer creates an
+issue for every unfulfilled bullet point so it can be fixed by the Elektra Initiative.
+
+## Checklist Legend
+
+- [ ] not fulfilled  
+       This is the reason for why its is not fulfilled
+- [x] fulfilled
+- not applicable
+
+## Templates
+
+The template and the script for generating review files based on that template
+can be found [here](/scripts/api_review/README.md)

doc/api_review/core/kdbClose.md

@@ -0,0 +1,83 @@
+# kdbClose
+
+- start = 2021-01-23 18:10
+- end = 2021-01-23 18:10
+- moderator = Stefan Hanreich <[email protected]>
+
+## Signature
+
+`int kdbClose(KDB *handle, Key *errorKey)`
+
+## Checklist
+
+#### Doxygen
+
+(bullet points are in order of appearance)
+
+- [ ] First line explains briefly what the function does
+- [ ] Simple example or snippet how to use the function
+- [ ] Longer description of function containing common use cases
+- [ ] Description of functions reads nicely
+- [ ] `@pre`
+- [ ] `@post`
+- [ ] `@invariant`
+- [ ] `@param` for every parameter
+- [ ] `@return` / `@retval`
+- [ ] `@since`
+- [ ] `@ingroup`
+- [ ] `@see`
+
+### Naming
+
+- [ ] Abbreviations used in function names must be defined in the
+      [Glossary](/doc/help/elektra-glossary.md)
+- [ ] Function names should neither be too long, nor too short
+- [ ] Function name should be clear and unambiguous
+- [ ] Abbreviations used in parameter names must be defined in the
+      [Glossary](/doc/help/elektra-glossary.md)
+- [ ] Parameter names should neither be too long, nor too short
+- [ ] Parameter names should be clear and unambiguous
+
+### Compatibility
+
+(only in PRs)
+
+- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md)
+      is correct for breaking changes
+- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility
+      to add additional symbols is fine)
+
+### Parameter & Return Types
+
+- [ ] Function parameters should use enum types instead of boolean types
+      wherever sensible
+- [ ] Wherever possible, function parameters should be `const`
+- [ ] Wherever possible, return types should be `const`
+- [ ] Functions should have the least amount of parameters feasible
+
+### Structural Clarity
+
+- [ ] Functions should do exactly one thing
+- [ ] Function name has the appropriate prefix
+- [ ] Order of signatures in kdb.h.in is the same as Doxygen
+- [ ] No functions with similar purpose exist
+
+### Memory Management
+
+- [ ] Memory Management should be handled by the function wherever possible
+
+### Extensibility
+
+- [ ] Function is easily extensible, e.g., with flags
+- [ ] Documentation does not impose limits, that would hinder further extensions
+
+### Tests
+
+- [ ] Function code is fully covered by tests
+- [ ] All possible error states are covered by tests
+- [ ] All possible enum values are covered by tests
+- [ ] No inconsistencies between tests and documentation
+
+## Summary
+
+## Other Issues discovered (unrelated to function)

doc/api_review/core/kdbEnsure.md

@@ -0,0 +1,83 @@
+# kdbEnsure
+
+- start = 2021-01-23 18:10
+- end = 2021-01-23 18:10
+- moderator = Stefan Hanreich <[email protected]>
+
+## Signature
+
+`int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey)`
+
+## Checklist
+
+#### Doxygen
+
+(bullet points are in order of appearance)
+
+- [ ] First line explains briefly what the function does
+- [ ] Simple example or snippet how to use the function
+- [ ] Longer description of function containing common use cases
+- [ ] Description of functions reads nicely
+- [ ] `@pre`
+- [ ] `@post`
+- [ ] `@invariant`
+- [ ] `@param` for every parameter
+- [ ] `@return` / `@retval`
+- [ ] `@since`
+- [ ] `@ingroup`
+- [ ] `@see`
+
+### Naming
+
+- [ ] Abbreviations used in function names must be defined in the
+      [Glossary](/doc/help/elektra-glossary.md)
+- [ ] Function names should neither be too long, nor too short
+- [ ] Function name should be clear and unambiguous
+- [ ] Abbreviations used in parameter names must be defined in the
+      [Glossary](/doc/help/elektra-glossary.md)
+- [ ] Parameter names should neither be too long, nor too short
+- [ ] Parameter names should be clear and unambiguous
+
+### Compatibility
+
+(only in PRs)
+
+- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md)
+      is correct for breaking changes
+- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility
+      to add additional symbols is fine)
+
+### Parameter & Return Types
+
+- [ ] Function parameters should use enum types instead of boolean types
+      wherever sensible
+- [ ] Wherever possible, function parameters should be `const`
+- [ ] Wherever possible, return types should be `const`
+- [ ] Functions should have the least amount of parameters feasible
+
+### Structural Clarity
+
+- [ ] Functions should do exactly one thing
+- [ ] Function name has the appropriate prefix
+- [ ] Order of signatures in kdb.h.in is the same as Doxygen
+- [ ] No functions with similar purpose exist
+
+### Memory Management
+
+- [ ] Memory Management should be handled by the function wherever possible
+
+### Extensibility
+
+- [ ] Function is easily extensible, e.g., with flags
+- [ ] Documentation does not impose limits, that would hinder further extensions
+
+### Tests
+
+- [ ] Function code is fully covered by tests
+- [ ] All possible error states are covered by tests
+- [ ] All possible enum values are covered by tests
+- [ ] No inconsistencies between tests and documentation
+
+## Summary
+
+## Other Issues discovered (unrelated to function)

doc/api_review/core/kdbGet.md

@@ -0,0 +1,83 @@
+# kdbGet
+
+- start = 2021-01-23 18:10
+- end = 2021-01-23 18:10
+- moderator = Stefan Hanreich <[email protected]>
+
+## Signature
+
+`int kdbGet(KDB *handle, KeySet *returned, Key *parentKey)`
+
+## Checklist
+
+#### Doxygen
+
+(bullet points are in order of appearance)
+
+- [ ] First line explains briefly what the function does
+- [ ] Simple example or snippet how to use the function
+- [ ] Longer description of function containing common use cases
+- [ ] Description of functions reads nicely
+- [ ] `@pre`
+- [ ] `@post`
+- [ ] `@invariant`
+- [ ] `@param` for every parameter
+- [ ] `@return` / `@retval`
+- [ ] `@since`
+- [ ] `@ingroup`
+- [ ] `@see`
+
+### Naming
+
+- [ ] Abbreviations used in function names must be defined in the
+      [Glossary](/doc/help/elektra-glossary.md)
+- [ ] Function names should neither be too long, nor too short
+- [ ] Function name should be clear and unambiguous
+- [ ] Abbreviations used in parameter names must be defined in the
+      [Glossary](/doc/help/elektra-glossary.md)
+- [ ] Parameter names should neither be too long, nor too short
+- [ ] Parameter names should be clear and unambiguous
+
+### Compatibility
+
+(only in PRs)
+
+- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md)
+      is correct for breaking changes
+- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility
+      to add additional symbols is fine)
+
+### Parameter & Return Types
+
+- [ ] Function parameters should use enum types instead of boolean types
+      wherever sensible
+- [ ] Wherever possible, function parameters should be `const`
+- [ ] Wherever possible, return types should be `const`
+- [ ] Functions should have the least amount of parameters feasible
+
+### Structural Clarity
+
+- [ ] Functions should do exactly one thing
+- [ ] Function name has the appropriate prefix
+- [ ] Order of signatures in kdb.h.in is the same as Doxygen
+- [ ] No functions with similar purpose exist
+
+### Memory Management
+
+- [ ] Memory Management should be handled by the function wherever possible
+
+### Extensibility
+
+- [ ] Function is easily extensible, e.g., with flags
+- [ ] Documentation does not impose limits, that would hinder further extensions
+
+### Tests
+
+- [ ] Function code is fully covered by tests
+- [ ] All possible error states are covered by tests
+- [ ] All possible enum values are covered by tests
+- [ ] No inconsistencies between tests and documentation
+
+## Summary
+
+## Other Issues discovered (unrelated to function)