summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorNikos Mavrogiannopoulos <nmav@gnutls.org>2016-05-14 00:31:43 +0200
committerNikos Mavrogiannopoulos <nmav@gnutls.org>2016-05-14 00:32:37 +0200
commit67d338d0fddf01d3b6a4506effb1a89c9f0a1869 (patch)
tree0d5c50e6cc003283a6dbd6280eff19cbdc85e934 /CONTRIBUTING.md
parent28e7edd96707d5f4f9df8fe0967e1ced3e88f91c (diff)
downloadgnutls-67d338d0fddf01d3b6a4506effb1a89c9f0a1869.tar.gz
Moved coding style and contribution guide to CONTRIBUTION.md
This aligns with gitlab's web interface.
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md143
1 files changed, 143 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..7567bf5ff8
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,143 @@
+# GnuTLS -- Information about our contribution rules and coding style
+
+ Anyone is welcome to contribute to GnuTLS. You can either take up
+tasks from our [planned list](https://gitlab.com/gnutls/gnutls/issues),
+or suprise us with enhancement we didn't plan for. In all cases be prepared
+to defend and justify your enhancements, and get through few rounds
+of changes.
+
+We try to stick to the following rules, so when contributing please
+try to follow them too.
+
+# Git commits:
+
+ The original author of the changes should be the author of the commit.
+The "Signed-off-by" git flag is used to by committers to indicate they
+agreed with project's DCO as described in [DCO.txt](doc/DCO.txt). Note
+that we not longer require FSF copyright assignment.
+
+# Test suite:
+
+ New functionality should be accompanied by a test case which verifies
+the correctness of GnuTLS' operation on successful use of the new
+functionality, as well as on fail cases. An example test suite can be seen
+in mini-x509-cas.c. The GnuTLS test suite is run on "make check"
+on every system GnuTLS is installed.
+
+
+# File names:
+
+ Files are split to directories according to the subsystem
+they belong to. Examples are x509/, minitasn1/, openpgp/,
+opencdk/ etc. The files in the root directory are of concern
+to the main TLS protocol implementation.
+
+
+# C dialect:
+
+ While parts of GnuTLS were written in older dialects, new code
+in GnuTLS are expected to conform to C99. Exceptions could be made
+for C99 features that are not supported in popular platforms on a
+case by case basis.
+
+
+# Indentation style:
+
+ In general, use the Linux kernel coding style. You may indent the source
+using GNU indent, e.g. "indent -linux *.c".
+
+
+# Function names:
+
+ All the function names use underscore "_", to separate words,
+functions like gnutlsDoThat are not used. The exported function names
+usually start with "gnutls_" prefix, and the words that follow
+specify the exact part of gnutls that this function refers to.
+E.g. "gnutls_x509_crt_get_dn", refers to the X.509
+certificate parsing part of gnutls. Currently used prefixes are:
+"gnutls_x509_crt_" for the X.509 certificate part
+"gnutls_openpgp_key_" for the openpgp key part
+"gnutls_session_" for the TLS session part (but this may be omited)
+"gnutls_handshake_" for the TLS handshake part
+"gnutls_record_" for the TLS record protocol part
+"gnutls_alert_" for the TLS alert protocol part
+"gnutls_credentials_" for the credentials structures
+"gnutls_global_" for the global structures handling
+and probably more.
+
+Internal functions -- that are not exported in the API -- should
+be prefixed with an underscore. E.g. _gnutls_handshake_begin()
+
+Internal structures should not be exported. Especially pointers to
+internal data. Doing so harms future reorganization/rewrite of subsystems.
+
+All exported functions must be listed in libgnutls.map.in
+in order to be exported.
+
+
+# Constructed types:
+
+ The constructed types in gnutls always have the "gnutls_" prefix.
+Definitions, value defaults and enumerated values should be in
+capitals. E.g. GNUTLS_CIPHER_3DES_CBC
+
+Structures should have the '_st' suffix in their name even
+if they are a typedef. One can use the sizeof() on types with
+'_st' as suffix.
+
+Other constructed types should have the '_t' suffix. A pointer
+to a structure also has the '_t' suffix.
+
+
+# Function parameters:
+
+The gnutls functions accept parameters in the order:
+ 1. Input parameters
+ 2. Output parameters
+
+When data and size is expected, a gnutls_datum structure should be
+used (or more precisely a pointer to the structure).
+
+
+# Callback function parameters:
+
+ Callback functions should be avoided, if this is possible.
+Callbacks that refer to a TLS session should include the
+current session as a parameter, in order for the called function to
+be able to retrieve the data associated with the session.
+This is not always done though -- see the push/pull callbacks.
+
+
+# Return values:
+
+ Functions in gnutls return an int type, when possible. In that
+case 0 should be returned in case of success, or maybe a positive
+value, if some other indication is needed.
+
+A negative value always indicates failure. All the available
+error codes are defined in gnutls.h and a description
+is available in gnutls_errors.c
+
+
+# Guile bindings:
+
+ Parts of the Guile bindings, such as types (aka. "SMOBs"), enum values,
+constants, are automatically generated. This is handled by the modules
+under `guile/modules/gnutls/build/'; these modules are only used at
+build-time and are not installed.
+
+The Scheme variables they generate (e.g., constants, type predicates,
+etc.) are exported to user programs through `gnutls.scm' and
+`gnutls/extra.scm', both of which are installed.
+
+For instance, when adding/removing/renaming enumerates or constants,
+two things must be done:
+
+ 1. Update the enum list in `build/enums.scm' (currently dependencies
+ are not tracked, so you have to run "make clean all" in `guile/'
+ after).
+
+ 2. Update the export list of `gnutls.scm' (or `extra.scm').
+
+Note that, for constants and enums, "schemefied" names are used, as
+noted under the "Guile API Conventions" node of the manual.