From 11dad4a8aeb8ae59e20dae0814ddb16fc388fc39 Mon Sep 17 00:00:00 2001
From: Chase Geigle <geigle1@illinois.edu>
Date: Wed, 7 Sep 2016 17:19:00 -0500
Subject: [PATCH] Add simple releasing and packaging/installing guides.

---
 PACKAGING.md | 38 ++++++++++++++++++++++++++++++++++
 RELEASING.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 PACKAGING.md
 create mode 100644 RELEASING.md

diff --git a/PACKAGING.md b/PACKAGING.md
new file mode 100644
index 000000000..208e259c8
--- /dev/null
+++ b/PACKAGING.md
@@ -0,0 +1,38 @@
+# Packaging or Installing MeTA
+
+Please follow these slightly modified build instructions if you are either
+a packager and you want to make a package of MeTA for your distribution, or
+if you simply want to install MeTA to e.g. `/usr/local`.
+
+You will need the following `cmake` flags:
+
+- `-DBUILD_SHARED_LIBS=On`: build `.so` libraries instead of `.a`.
+- `-DBUILD_STATIC_ICU=On`: force building a static ICU library as part of
+    `meta-utf.so` to ensure Unicode standard stability.
+
+If you are building for a Linux platform, you *must* use GCC. **Do not use
+Clang/libc++**, as the library throws exceptions and must be built in the
+same way all other C++ applications on the system are expected to be built.
+
+MeTA will require [cpptoml][cpptoml] to be installed. This is
+straightforward as cpptoml is header-only. Please follow the standard
+`cmake` build instructions for cpptoml and package using `make install` to
+install the CMake configuration files for cpptoml. This allows MeTA's CMake
+configuration files to find cpptoml as a dependency.
+
+MeTA can then be installed using `make install`.
+
+# Using an Installed MeTA
+
+You can consume MeTA most easily by using a CMake build system (though you
+do not have to). Your `CMakeLists.txt` might look something like the
+following:
+
+```cmake
+find_package(MeTA 2.4 REQUIRED)
+
+add_executable(my-program my_program.cpp)
+target_link_libraries(my-program meta-index) # or any other MeTA libraries
+```
+
+[cpptoml]: https://github.com/skystrife/cpptoml
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 000000000..6bdab06b2
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,58 @@
+# Releasing MeTA Versions
+
+This document contains a checklist for releasing a version of MeTA so we
+follow a consistent releasing process.
+
+1. Pick a version number. MeTA releases (Major.Minor.Patch) ought to be API
+   compatible with other releases that share the same Major and Minor
+   version numbers but different Patch versions.
+
+   Major API changes (like new libraries or toolkit-wide backwards
+   incompatible API changes) increment the Major release number. Minor API
+   changes (like enhancements) increment the Minor release number. Patch
+   versions should be released only for bug fixes.
+
+2. Ensure `CHANGELOG.md` is up to date.
+
+   If there are *any* breaking changes, mention these explicitly. If there
+   are migration strategies to work around these breaking changes, provide
+   a brief explanation (or a link to explain them).
+
+3. If there are major *or* minor API changes, ensure that the documentation
+   on the website (meta-toolkit/meta-toolkit.org) is correct.
+
+   Update Doxygen as necessary.
+
+4. Ensure that the build is passing on both Travis (Linux + OS X) and
+   Appveyor (Windows/MinGW-w64).
+
+5. Merge branch `develop` into `master` with a commit message
+
+   > Merge branch 'develop' for MeTA vX.Y.Z
+
+   Use `git merge develop --no-ff` to create a merge commit.
+
+6. Tag the merge commit. The tag should be both annotated *and* signed:
+
+   ```
+   git tag -as vX.Y.Z
+   ```
+
+   The tag message should be the contents of the CHANGELOG for that
+   version. Remove unnecessary markdown syntax like header markers and code
+   blocks. Backticks can stay.
+
+7. Push the merge and the tags to GitHub:
+
+   ```
+   git push --follow-tags
+   ```
+
+8. Create a release on GitHub using the new tag. Its title should be "MeTA
+   vX.Y.Z".
+
+   The contents of the message should be exactly the same as the CHANGELOG
+   entry for that release.
+
+9. Upload the model files and include a section in the GitHub release notes
+   containing their sha256 sums.