Adding upstream version 0.17.0.upstream/0.17.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 249 insertions, 0 deletions

diff --git a/docs/develop/cpp-usage.adoc b/docs/develop/cpp-usage.adoc
new file mode 100644
index 0000000..e0c1842
--- /dev/null
+++ b/docs/develop/cpp-usage.adoc
@@ -0,0 +1,49 @@
+= Usage of {cpp} within RNP
+
+This is a provisional document reflecting the recent conversion from C
+to {cpp}. It should be revisited as experience with using {cpp} within RNP
+codebase increases.
+
+== Encouraged Features
+
+These are features which seem broadly useful, their downsides are minimal
+and well understood.
+
+ - STL types std::vector, std::string, std::unique_ptr, std::map
+
+ - RAII techniques (destructors, smart pointers) to minimize use of
+   goto to handle cleanup.
+
+ - Value types, that is to say types which simply encapsulate some
+   data.
+
+ - std::function or virtual functions to replace function pointers.
+
+ - Prefer virtual functions only on "interface" classes (with no data),
+   and derive only one level of classes from this interface class.
+
+ - Anonymous namespaces are an alternative to `static` functions.
+
+== Questionable Features
+
+These are features that may be useful in certain situations, but should
+be used carefully.
+
+ - Exceptions. While convenient, they do have a non-zero cost in runtime
+   and binary size.
+
+== Forbidden Features
+
+These are {cpp} features that simply should be avoided, at least until a
+very clear use case for them has been identified and no other approach
+suffices.
+
+ - RTTI. This has a significant runtime cost and usually there are
+   better alternatives.
+
+ - Multiple inheritance. This leads to many confusing and problematic
+   scenarios.
+
+ - Template metaprogramming. If you have a problem, and you think
+   template metaprogramming will solve it, now you have two problems,
+   and one of them is incomprehensible.
diff --git a/docs/develop/packaging.adoc b/docs/develop/packaging.adoc
new file mode 100644
index 0000000..917c9aa
--- /dev/null
+++ b/docs/develop/packaging.adoc
@@ -0,0 +1,78 @@
+= Packaging
+
+== CentOS 7
+
+=== 1. Retrieve the source
+
+==== Tarball
+
+[source,console]
+--
+curl -LO https://github.com/rnpgp/rnp/archive/v0.9.0.tar.gz
+tar xzf v0.9.0.tar.gz
+cd rnp-0.9.0
+--
+
+==== Git
+
+[source,console]
+--
+git clone https://github.com/rnpgp/rnp
+cd rnp
+git checkout v0.9.0
+--
+
+=== 2. Launch a container
+
+[source,console]
+--
+docker run -ti --rm -v $PWD:/usr/local/rnp centos:7 bash
+--
+
+From this point, all commands are executed in the container.
+
+==== 3. Install pre-requisites
+
+[source,console]
+--
+# for newer cmake and other things
+yum -y install epel-release
+
+# rnp
+yum -y install git cmake3 make gcc-c++
+yum -y install bzip2-devel zlib-devel json-c12-devel
+
+# botan
+rpm --import https://github.com/riboseinc/yum/raw/master/ribose-packages.pub
+rpm --import https://github.com/riboseinc/yum/raw/master/ribose-packages-next.pub
+curl -L https://github.com/riboseinc/yum/raw/master/ribose.repo > /etc/yum.repos.d/ribose.repo
+yum -y install botan2-devel
+--
+
+=== 4. Build the RPM
+
+[source,console]
+--
+yum -y install rpm-build
+mkdir ~/build
+cd ~/build
+cmake3 -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off -DCPACK_GENERATOR=RPM /usr/local/rnp
+make package
+--
+
+=== 5. Check and Install the RPM
+
+It may be helpful to run `rpmlint` on the RPM and note new warnings or errors.
+
+[source,console]
+--
+yum -y install rpmlint
+rpmlint rnp-0.9.0-1.el7.centos.x86_64.rpm
+--
+
+At this point, you can test that the RPM installs successfully:
+
+[source,console]
+--
+yum localinstall rnp-0.9.0-1.el7.centos.x86_64.rpm
+--
diff --git a/docs/develop/release-workflow.adoc b/docs/develop/release-workflow.adoc
new file mode 100644
index 0000000..40f4203
--- /dev/null
+++ b/docs/develop/release-workflow.adoc
@@ -0,0 +1,122 @@
+= Releases
+
+== General notes
+
+* Avoid tagging commits in the `main` branch.
+* Release branches should have annotated tags and a CHANGELOG.md.
+* The steps below detail creation of a brand new 1.0.0 release.
+  Some steps would be omitted for minor releases.
+
+== Creating an initial release
+
+=== Update documentation
+
+Update references to version numbers in relevant documentation to the new
+version you intend to release.
+
+[source,console]
+----
+git checkout main
+vim docs/installation.adoc
+git add docs/installation.adoc
+git commit
+git push
+----
+
+=== Create branch
+
+Release branches have names of the form `release/N.x`, where N is the major
+version (and `x` is a literal -- not a placeholder).
+
+[source,console]
+----
+git checkout -b release/1.x main
+----
+
+[[update-changelog-and-version]]
+=== Update CHANGELOG and version
+
+[source,console]
+----
+vim CHANGELOG.md
+# Add/update CHANGELOG entry for the new version
+git add CHANGELOG.md
+
+echo 1.0.0 > version.txt
+git add -f version.txt
+
+git commit
+----
+
+=== Create tag
+
+An initial release would be tagged as follows:
+
+[source,console]
+----
+git tag -a v1.0.0 -m ''
+----
+
+=== Push branch and tag
+
+[source,console]
+----
+# push the branch
+git push origin release/1.x
+
+# push the tag
+git push origin v1.0.0
+----
+
+=== Edit tagged release description on GitHub
+
+. Navigate to the link:#https://github.com/rnpgp/rnp/releases[Releases] page;
+
+. Edit the tag that was just pushed;
+
+. Fill the tag's description with data from the corresponding `CHANGELOG`
+  entries of the same tag version;
+
+. Publish the release.
+
+
+== Creating a new release
+
+Maintaining a release branch involves cherry-picking hotfixes and
+similar commits from the `main` branch, while following the rules for
+Semantic Versioning.
+
+The steps below will show the release of version 1.0.1.
+
+=== Add desired changes
+
+Cherry-pick the appropriate commits into the appropriate `release/N.x` branch.
+
+To see what commits are in `main` that are not in the release branch, you
+can observe the lines starting with `+` in:
+
+[source,console]
+----
+git cherry -v release/1.x main
+----
+
+It is often useful to pick a range of commits. For example:
+
+[source,console]
+----
+git checkout release/0.x
+git cherry-pick a57b36f^..e23352c
+----
+
+If there are merge commits in this range, this will not work.
+Instead, try:
+
+[source,console]
+----
+git checkout release/0.x
+git cherry release/0.x main | grep '^+ ' | cut -c 3-9 | \
+  while read commit; do git cherry-pick $commit; done
+----
+
+From here, you can follow the steps for an initial release,
+starting with <<update-changelog-and-version>>.