summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorNikos Mavrogiannopoulos <nmav@redhat.com>2017-09-25 16:57:31 +0200
committerNikos Mavrogiannopoulos <nmav@redhat.com>2017-09-27 09:19:29 +0200
commitf0ed57053f92ab184c9e16973a5352f24d6c1722 (patch)
tree68c1020a9cfad79d6a29f2c2aae983e06b61ec1b /CONTRIBUTING.md
parent17bc86f541ec5ac8a4fd1460f8bbe24e76ad236b (diff)
downloadgnutls-f0ed57053f92ab184c9e16973a5352f24d6c1722.tar.gz
CONTRIBUTING.md: added some text on introducing new APIs [ci skip]
Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md20
1 files changed, 19 insertions, 1 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b63cfa5185..bec4f00284 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -77,7 +77,6 @@ E.g. ```gnutls_x509_crt_get_dn```, refers to the X.509
certificate parsing part of gnutls. Some of the used prefixes are the
following.
* ```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
@@ -95,6 +94,25 @@ All exported functions must be listed in libgnutls.map.in,
in order to be exported.
+# Introducing new functions / API
+
+ Prior to introducing any new API consider all options to offer the same
+functionality without introducing a new function. The reason is that we want
+to avoid breaking the ABI, and thus we cannot typically remove any function
+that was added (though we have few exceptions). Since we cannot remove, it
+means that experimental APIs, or helper APIs that are not typically needed
+may become a burden to maintain in the future. That is, they may prevent
+a refactoring, or require to keep legacy code.
+
+As such, some questions to answer before adding a new API:
+ * Is this API useful for a large class of applications, or is it limited
+ to few?
+ * If it is limited to few, can we work around that functionality without
+ a new API?
+ * Would that function be relevant in the future when a new protocol such TLS
+ 13.0 is made available? Would it harm the addition of a new protocol?
+
+
# Constructed types:
The constructed types in gnutls always have the ```gnutls_``` prefix.