[Amforth] Gory Details: How to properly create a release?

[Erich W. <ew....@na...>]

Dear AmForthers,

I asked:
>  - How do I actually create a new release? Copying the files is
>    one thing, but where do I need to change the version? There
>    is more than one place, I'm afraid. I also happen to know
>    that after 6.9 there cannot be 6.10 due to a limitation
>    created very early. Matthias told me that, otherwise I would
>    be clueless.
see https://sourceforge.net/p/amforth/mailman/message/37048278/



How to create an official release?

I spent some time to do some code archeology. I still do not know,
how to properly make a release. This is, what I currently
see/expect:

1. check all version numbers in trunk

   - doc/Makefile being one place. This seems to be used in all
     generated documentation, which is nice.
   - common/words/env-forthversion.asm is another place with different
     syntax!
   Judging by commit r2271, these are all places indeed. Yay!

2. update doc/source/index.rst and optionally history.rst in
   trunk and commit

3. "svn copy" trunk to releases/$VERSION; commit message collects
   the accumulated one line change descriptions
   This is the most visible change in the source tree
   e.g. see commit r2244 (rel 6.5)

4. create all .hex files for target boards in appl/
   arduino,atmega2561,eval-pollin,hifive1,launchpad-arm,launchpad430,
   template

   I had forgotten that these exsisted. They are in the release archive
   only, not in the source tree. Now I understand, why people
   sometimes ask about them.

   This step is detailed in a few .xml files. Matthias used ant to
   build them. I have not built these before, but this looks doable,
   provided I get all relevant toolchains up and running.

5. create the documentation
   - htdocs, the web page
   - books, did you know that all the content of the webpage shows up
     in amforth.pdf (made with pdflatex) and AmForth.epub (made with
     sphinx-build)? Amazing! These books are part of the download .zip
     archive.

     This step is a "cd doc; make all" --- provided sphinx pdflatex
     and all the good stuff is installed.

6. create a new temporary tree to collect everything, that goes into
   the release archive:
   - sources
   - some of the scripts, tools, meta-files
   - the generated documentation from releases/$VERSION, without the
     document sources, but including the "books"

   I have not found anything that looks like doing this.

7. create the .zip and .tar.gz archives (the easy part), and upload
   them to their correct location in the sourceforge.net file tree
   (the not so obvious part).

   I found out that these release archives were built by Matthias.
   The files for 6.8 are about 7 MB in size.

   Whereas if you download "the latest sources", sourceforge will
   generate a snapshot of "trunk". This is a plain copy, without all
   the niceties included in the archives mentioned here. This archive
   is currently 35 MB in size.

8. sync the generated documentation with the online website

   I have done this a few times now, but I'm still asking myself, if I
   see all relevant pieces or not.

9. Increment the version numbers in trunk and commit


So nine easy steps to code nirvana? Hmmm.

If anyone has some insight or detail I'm missing, I would be
happy to hear about it. I propose to rework this into a .rst
document and add it to the source tree, once missing bits have
emerged (points 4, 6, 7).

Cheers,
Erich

-- 
May the Forth be with you ...