Merge pull request #466 from Haskell-Things/rework_release

fix typo in .gitignore, and mostly rewrite the release process.

.gitignore

@@ -25,7 +25,7 @@ dist/
 dist-newstyle/
 .ghc.environment.*
 # Generated documentation.
-docs/iscad.md
+docs/escad.md
 # Generated by examples
 Examples/*cachegrind*
 Examples/example[0-9][0-9]

Release.md

@@ -1,81 +1,76 @@
 # Release Processes:
 
-Purpose of this document: to make sure i follow a consistent patern, when making changes to ImplicitCAD.
-
-## "no point" releases:
-
-### Comment / Format / Messages
-
-These changes don't improve anything but the code quality, messages output, or build system. they can add features to the parser, but cannot remove them. they may not change the md5 of the generated STL files.
-
-1. make sure test-implicit is all green.
-2. make sure docgen hasn't changed it's output too much.
-3. make sure parser-bench does not show any unacceptable speed reductions.
-4. make sure Benchmark does not show any unacceptable speed reductions.
+Purpose of this document: to make sure we follow a consistent pattern, when making releases of ImplicitCAD.
+
+## Version Logic:
+1. The first digit is always 0. Maybe we'll change this when we're ready for the masses. ;)
+2. The second digit changes with "major" releases.
+ * Major releases change:
+   * the CSG representation (the MD5sum of generated output files)
+   * the Haskell interface (in a non-additive fashion)
+   * or the SCAD interface (in a non-additive fashion)
+3. The third digit changes with the "minor" releases.
+ * Minor releases DO NOT change:
+   * the CSG representation (the MD5sum of generated output files)
+   * the Haskell interface (in a non-additive fashion)
+   * or the SCAD interface (in a non-additive fashion)
+ * Minor releases may change anything else.
+4. The fourth digit changes with the "trivial" releases.
+ * Trivial releases change nothing except the documentation.
+
+## Tests for a Minor Release
+1. make sure the output of the test-implicit binary is all green.
+2. make sure the output of the docgen executable hasn't changed too greatly since the last release.
+  * run `make docs`
+  * examine the difference in the docs/escad.md
+3. make sure the output of the parser-bench binary does not show any unacceptable speed reductions.
+4. make sure the output of the Benchmark binary does not show any unacceptable speed reductions.
 5. make sure the md5sum of the stl files resulting from running 'make examples' have not changed.
 
-push to master.
-
-### Math / Types
-These releases change the math engine, but only in a direction that is provably better, and shows in our examples.
-
-1. do all of the above.
-2. check 'make examples' output. look at the times that valgrind measures.
-3. check the md5sum of the .stl files output.
-
-If the md5sums of the last release and this one differ, run admesh on both, and examine the output. if the output is conclusively better for all changed examples, then proceed to push.
-
-push to master.
-
-## point releases:
-
-These releases change the quality of the output significantly enough that poking it with admesh is indeterminate, or they include changes to the parser such that old code would not work.
-
-## major releases:
+## Performing a release
 
-These bring new features, and other improvements that are considered to be 'major'.
+### Create a Release branch
+1. git checkout -b release/<VERSION>
+2. update the Version field in implicit.cabal.
+3. update the Version in the README.md.
+4. change the most recent Version line in CHANGELOG.md from 'next', updating the following fields on that line.
+5. push the branch to github, and file a pull request.
 
-### Process:
-merge the release PR in github.
+## Merge to master
+In the github interface, after all of the tests are green, merge to the master branch.
 
-on your git machine:
- * make sure 'cabal haddock' works.
-
-
-
-#### Tagging a release
-on your git machine:
+### Tagging a release
+On your git machine:
 ```
+export VERSION=<VERSION_NUMBER>
 git checkout master
-git tag -a v0.4.0.0 -m 'release 0.4.0.0'
-git push origin v0.4.0.0
-```
-
-#### Publishing the release to hackage
-
-use github's 'download zip' to download a zip of the package.
-extract it to a temporary directory
-move the container directory to implicit-<VERSIONNUMBER>
-make a tar file from it. make sure to add the --format=ustar option.
-```
-tar --format=ustar -cvzf implicit-0.4.0.0.tar.gz implicit-0.4.0.0/
+git tag -a v$VERSION -m "Release $VERSION"
+git push origin v$VERSION
 ```
-upload package candidate to https://hackage.haskell.org/packages/candidates/upload
-look over the resulting page.
-
-scroll down to 'edit package information'
-
-click on 'publish candidate'
-
-hit the 'publish package' button.
 
 #### Publishing the release to GitHub
 
-open github.
-hit the 'Releases' link from the code page for the repo.
-hit 'draft a new release
-select the tag.
-paste the CHANGELOG entries in the description.
-title the release 'Release <versionnumber>'
-hit 'Publish release'
+1. Open Github.
+2. Click on the 'Releases' link from the code page for the implicitcad repo.
+3. Click on 'draft a new release'
+4. Select the tag created in the previous step.
+5. Paste the CHANGELOG.md entries from this release into the release description.
+6. Title the release 'Release <versionnumber>'
+7. Click on 'Publish release'
+
+#### Publishing the release to Hackage
+
+1. Use github's 'download zip' to download a zip of the package.
+2. Extract it to a temporary directory
+3. Move the container directory to implicit-<VERSIONNUMBER>
+4. Make a tar file from it. make sure to add the --format=ustar option.
+ * tar --format=ustar -cvzf implicit-0.4.0.0.tar.gz implicit-0.4.0.0/
+5. Upload the package candidate to https://hackage.haskell.org/packages/candidates/upload
+6. Look over the resulting page.
+7. Scroll down to 'edit package information'
+8. click on 'publish candidate'
+9. hit the 'publish package' button.
+
+#### Update ImplicitCAD.org
+1. Use the output of docgen to update implicitcad.org (fixme: how?)