As promised.
The file is plain ascii .org mode format:
--- Howto-make-a-release.org -----------------------------------
# 2020-10-12 amforth/erwaelde
* How to properly make a release?
Somewhat machine readable version.
** Intro
#+begin_quote
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.
#+end_quote
** Go to the correct directory
#+begin_src sh
cd ~/eGeek/sourceforge.net/amforth-code
#+end_src
** Check current Version Strings
Fortunately only three files:
#+begin_src sh
(
cd trunk
grep '^VERSION' doc/Makefile
cat common/words/env-forthversion.asm
cat shared/words/env-forthversion.s
)
#+end_src
** update doc/source/index.rst
Do /not/ delete any blank lines in this file, they are sorely needed!
#+begin_src diff
ew@ceres:~/eGeek/sourceforge.net/amforth-code 7 > svn diff trunk/
Index: trunk/doc/source/index.rst
===================================================================
--- trunk/doc/source/index.rst (revision 2451)
+++ trunk/doc/source/index.rst (working copy)
@@ -36,6 +36,9 @@
See the code section at Sourceforge to get the
`most recent sources
<http://sourceforge.net/p/amforth/code/HEAD/tree/trunk/>`__
+18.10.2020: release 6.9
+.......................
+
* tools/amforth-shell.py fixed python3 error (in --no-error-on-output
option path), fix provided by Tristan Williams.
* tools/amforth-shell.py fixed indentation error in line 1146, fix provided by
Tristan Williams.
#+end_src
: svn commit trunk/doc/source/index.rst -m 'call it version 6.9'
: svn up
** create releases/$Version
#+begin_src sh
svn cp trunk/ releases/6.9
#+end_src
Alle ? Dateien werden hier mitkopiert, aber wenigstens nicht mit
add verziert. Aha.
edit svn.msg, collect all comments from index.rst since last release
: svn commit . --file svn.msg
: svn up
** increment $Version
: vi trunk/doc/Makefile
: vi trunk/common/words/env-forthversion.asm
: vi trunk/shared/words/env-forthversion.s
: svn commit trunk/doc/Makefile trunk/common/words/env-forthversion.asm
trunk/shared/words/env-forthversion.s -m 'Increment version to 7.0'
** commit
see e.g. r2432 .. r2434
** checkout a temp. release tree
#+begin_src sh
cd ~
mkdir tmp-amforth-code
cd tmp-amforth-code
svn checkout svn://svn.code.sf.net/p/amforth/code/releases/6.9
cd 6.9
# add Atmel AvrAsm2 tree
wget
https://sourceforge.net/projects/amforth/files/Atmel-AVR8-Assembler/Atmel-Assembler.tgz
tar xf Atmel-Assembler.tgz # unpacks into ./avr8/Atmel
(
cd appl
( cd hifive1 && make ) # hifive1, riscv64-linux-gnu-as
( cd linux-arm && make ) # linux-arm, arm-linux-gnueabi-as
( cd launchpad-arm && make ) # launchpad-arm, arm-none-eabi-as
( # several, wine AvrAsm2
for DIR in arduino atmega2561 eval-pollin template
do
( cd $DIR; ant compile )
done
)
)
#+end_src
** in release/$Version create .hex files
Das hab ich neulich mal ausgetüftelt:
#+begin_src sh
# once, on Debian 10 at this moment:
(
sudo -i
apt install binutils-riscv64-linux-gnu binutils-arm-linux-gnueabi
binutils-arm-none-eabi
)
(
cd ~/Projekte/17_naken_asm
git clone https://github.com/mikeakohn/naken_asm
cd naken_asm
./configure
make
./naken_asm | grep -i version # Version: March 15, 2020 # BROKEN ???
cp ./naken_asm ~/bin/
naken_asm | grep -i version # Version: December 28, 2015
)
tar xf ~/Forth/amforth/Atmel-Assembler.tgz
mv avr8/Atmel/ .
rmdir avr8
# always:
(
cd release/6.9
( cd avr8 && ln -snf ../../../Atmel . )
cd appl
( cd hifive1 && make ) # hifive1, riscv64-linux-gnu-as
( cd linux-arm && make ) # linux-arm, arm-linux-gnueabi-as
( cd launchpad-arm && make ) # launchpad-arm, arm-none-eabi-as
( # several, wine AvrAsm2
for DIR in arduino atmega2561 eval-pollin template
do
( cd $DIR; ant compile )
done
)
# launchpad430, naken_asm
( cd launchpad430 && make lp-2553.hex lp-5529.hex lp-5969.hex )
)
#+end_src
TEST them!!! This is the unresolved bit at this moment ...
no need to commit the artefacts. They are included in the
release-$version.tar.gz archive.
** in release/$Version build the documentation
#+begin_src sh
(
cd release/6.9/
rm -fr ./avr8/Atmel ./doc/Projects ./doc/build
cd doc
make all sitemap
)
#+end_src
** create a new release tar archive
#+begin_src sh
(
version=6.9
cd release/${version}
mkdir ../amforth-${version}
cp -a examples/ avr8/ LICENSE.txt \
risc-v/ appl/ shared/ common/ arm/ readme.txt msp430/ tests/ \
../amforth-${version}/
mkdir ../amforth-${version}/tools
cp -a tools/{am4up.c,amforth-upload.py,amforth-shell.py}
../amforth-${version}/tools
mkdir ../amforth-${version}/doc
cp -a doc/build/htdocs/ ../amforth-${version}/doc/
mkdir ../amforth-${version}/doc/tools
cp -a doc/tools/{forth.py,_mapping.py} ../amforth-${version}/doc/tools/
mv ../amforth-${version}/doc/htdocs/AmForth.epub ../amforth-${version}/doc/
mv ../amforth-${version}/doc/htdocs/amforth.pdf ../amforth-${version}/doc/
cd ..
tar -czvf amforth-${version}.tar.gz ./amforth-${version}
zip -r amforth-${version}.zip amforth-${version}
)
#+end_src
Wenn man die Unterschiede zum 6.8 tar.gz anguckt:
- -104 ich hab viele no-jtag.asm weggeschmissen.
- +4 ich hab in launchpad430 hex files gebaut, die fehlen in 6.8
- +4 Opinion
- +58 Projects/ClockWorks
- +2 Projects/RS485
- +2 refcard
- +3 .js .css
- +20 doc/_images
Die Zahl kann ich jetzt nicht komplett nachvollziehen, aber die
Unterschiede sind plausibel. Das passt so schon einigermaßen.
** create the new website and sync
die wohnt jetzt unter
: releases/6.9/doc/build/htdocs
oder?
** Increment Version numbers in trunk and commit
#+begin_src sh
(
cd trunk/doc
sed -i.bak -e '/^VERSION/s/6.9/7.0/' Makefile
)
(
cd trunk/common/words
sed -i.bak -e 's/\.dw 69/\.dw 70/' env-forthversion.asm
)
svn st
svn commit trunk/doc/Makefile trunk/common/words/env-forthversion.asm -m 'start
version 7.0'
#+end_src
** upload release tar archive(s)
** send announcement
** update the website!!!
#+begin_src sh
cd ~
mkdir tmp-amforth-website
cd tmp-amforth-website
svn checkout svn://svn.code.sf.net/p/amforth/code/trunk
cd trunk/doc
make htdocs
cd ~/eGeek/sourceforge.net/amforth-web/
mkdir amforth-2020-10-18-upload
cp -a amforth/amforth_config.xml amforth/cgi-bin/ amforth/upload
amforth-2020-10-18-upload/
cp -a ~/tmp-amforth-website/trunk/doc/build/htdocs/ amforth-2020-10-18-upload/
cd amforth-2020-10-18-upload/
rsync -vax --delete . [email protected]:/home/project-web/amforth
#+end_src
puhh.
----------------------------------------------------------------
--
May the Forth be with you ...
_______________________________________________
Amforth-devel mailing list for http://amforth.sf.net/
[email protected]
https://lists.sourceforge.net/lists/listinfo/amforth-devel
