DEV_NOTES.txt

checklist for doing a release:

1. Check to make sure weewx.conf doesn't have any local changes.
    In particular, check to make sure:
     1. WEEWX_ROOT points to /home/weewx
     2. debug=0 in weewx.conf
2. Make sure the correct version has been entered:
     1. weewx.__init__.py
     2. weewx.conf
     3. customizing.htm hardware.htm upgrading.htm usersguide.htm utilities.htm
3. Make sure all changes have been logged
     1. docs/changes.txt
     2. pkg/debian/changelog
     3. pkg/changelog.rpm
4. Make sure the upgrading guide has been updated if necessary.
5. If working off a branch, do a merge to master.
6. Create the tarball:  ./setup.py sdist
7. As a final sanity check, go to the production machine, unpack the
     tarball, install, run.
8. Tag it:  git tag -a v1.3.1 -m "Version 1.3.1 release"
9. Upload to weewx.com:
     1. make upload-src
     2. make upload-readme
10. Update docs on the web site:
     1. make upload-docs
11. Update the web site:
     1. Add to the news page.
     2. Upload news.htm to the web server.
12. Run a backup on condor
13. Announce the release to the weewx user's group.



release process by command: ---------------------------------------------------

# on any host, do a fresh checkout, set the version and update changelogs
git clone https://github.com/weewx/weewx.git
vi bin/weewx/__init__.py
make version
make deb-changelog
make rpm-changelog
vi docs/changes.txt        # as needed
vi docs/upgrading.htm      # as needed
git commit -a -m "release x.y.z"
git push

# generate the readme then upload it to development_versions
make readme upload-readme

# build src, upload to development_versions
rm -rf build dist
make src-package upload-src

# on debian host, build deb package, upload to development_versions
rm -rf build dist
make deb-package upload-deb

# on redhat host, build the redhat rpm package, upload to development_versions
rm -rf build dist
make rpm-package upload-rpm

# on suse host, build the suse rpm package, upload to development_versions
rm -rf build dist
make rpm-package upload-rpm

# tag the release
git tag -a vX.Y.Z -m "tag release X.Y.Z"

# upload the docs
git clone https://github.com/weewx/website.git
make upload-docs

# move the new files into position
mv development_versions/weewx-x.y.z* .
mv development_versions/README.txt .


howto -------------------------------------------------------------------------

create README.txt:
  make readme

how to update the version number:
  perl -pi -e 's/__version__=".*"/__version__="x.y.z"/' bin/weewx/__init__.py
  make version                  # this propagates the version number everywhere
  git commit -a -m "bump to version x.y.z"

how to build source package:
  make src-package

how to build debian package:
  make deb-changelog
  emacs pkg/debian/changelog    # add any package-specific changes, if any
  git commit -m "update deb changelog" pkg/debian/changelog
  make deb-package

how to build redhat package:
  make rpm-changelog
  emacs pkg/changelog.rpm       # add any package-specific changes, if any
  git commit -m "update rpm changelog" pkg/changelog.rpm
  make rpm-package

to display debconf variables:
  sudo debconf-show weewx

to manually purge debconf variables:
  sudo echo PURGE | debconf-communicate weewx

to sign rpm packages you need .rpmmacros in your home directory:
~/.rpmmacros
  %_signature gpg
  %_gpg_name  Matthew Wall

to generate gpg key used for signing packages:
  gpg --gen-key
  gpg --list-keys

to export the text version of a public key:
  gpg --export -a "Matthew Wall" > mwall.gpg.key

source install:
  setup.py install
  setup.py install home=/opt/weewx-x.y.z

debian install/remove:
  dpkg -i weewx_x.y.z-r.deb           # install
  (apt-get install weewx)             # finish install if dependencies failed
  dpkg -r weewx                       # remove
  dpkg -P weewx                       # purge

redhat install/remove:
  yum install weewx-x.y.z-r.rpm [--nogpgcheck]    # install with yum
  yum remove weewx                                # remove with yum
  rpm -i weewx-x.y.z-r.rpm                        # install with rpm directly
  rpm -e weewx                                    # remove with rpm

create debian repo using aptly:
  aptly repo create -distribution=squeeze -component=main weewx
  aptly repo add weewx dist/weewx_3.0.0-1_all.deb
  aptly snapshot create weewx-3.0.0 from repo weewx
  aptly -architectures="all" publish snapshot weewx-3.0.0

update debian repo using aptly:
  aptly repo add weewx dist/weewx_3.0.1-1_all.deb
  aptly snapshot create weewx-3.0.1 from repo weewx
  aptly -architectures="all" publish switch squeeze weewx-3.0.1

clone the published apt repo at godaddy to local space:
  mkdir -p ~/.aptly
  rsync -arv --rsync-path /home/content/t/o/m/tomkeffer/bin/rsync -e ssh USER@weewx.com:/home/content/t/o/m/tomkeffer/html/aptly/ ~/.aptly

synchronize local aptly changes with the published apt repo at godaddy:
  rsync -arv --rsync-path /home/content/t/o/m/tomkeffer/bin/rsync -e ssh ~/.aptly/ USER@weewx.com:/home/content/t/o/m/tomkeffer/html/aptly

for clients to use an apt repo at weewx.com:
  curl -s http://weewx.com/keys.html | sudo apt-key add -
  echo "deb [arch=all] http://weewx.com/apt/ squeeze main" | sudo tee /etc/apt/sources.list.d/weewx.list


notes -------------------------------------------------------------------------

there are multiple changelogs:
  docs/changes.txt - definitive changelog for the application
  pkg/debian/changelog - changes to the debian packaging
  pkg/changelog.rpm - changes to the redhat packaging
  README.txt - copy of changes.txt uploaded to download area

when signing, gpg info must match the name and email in the latest package
changelog entry.

the debian changelog *must* have a version number that matches the app version.
the redhat package will build if the version numbers do not match.  use the
rpm-changelog and deb-changelog targets to ensure that changelog versions match
the application version for a release.

there are many ways to build a debian package.  first tried dpkg (uses DEBIAN
dir and is fairly low-level) but that does not create changes and source diffs.
then dried dpkg-buildpackage (uses debian dir and is higher level) but misses
the config and templates.  ended up using dpkg-buildpackage with some manual
(scripted) file manipulation.

to do debian builds you must first install:
  python-imaging
  python-configobj
  debhelper

to do repo updates you must first install aptly:
  https://www.aptly.info/download/
for example, on debian:
  echo "deb http://repo.aptly.info/ squeeze main" | sudo tee /etc/apt/sources.list.d/aptly.list
  wget -qO - https://www.aptly.info/pubkey.txt | sudo apt-key add -
  sudo apt-get update
  sudo apt-get install aptly


unit tests --------------------------------------------------------------------

prerequisites:

python 2.7
python-mock 0.6

to set up mysql server with user and permissions for testing:

make test-setup

to run all unit tests:

make test

to clean up after running tests:

make test-clean

guidelines:

unit tests should put transient files in /var/tmp/weewx_test


testing -----------------------------------------------------------------------

what to test when creating debian and redhat packages:
  install, upgrade, remove, purge
  install, modify files, remove
  install, modify files, upgrade

any linux:
- new install using setup.py to /home/weewx
  setup.py install

- upgrade using setup.py to /home/weewx
  setup.py install
  modify /home/weewx/weewx.conf
  setup.py install

- new install using setup.py to /opt/weewx
  setup.py install home=/opt/weewx

- upgrade using setup.py to /opt/weewx
  setup.py install home=/opt/weewx
  modify /opt/weewx/weewx.conf
  setup.py install home=/opt/weewx

on centos and suse:

- new install using rpm
  rpm -i weewx_x.y.z.rpm

- upgrade using rpm
  rpm -i weewx_r.s.t.rpm
  rpm -U weewx_x.y.z.rpm

- upgrade using rpm with extensions installed
  rpm -i weewx_r.s.t.rpm
  wee_extension --install cmon
  rpm -U weewx_x.y.z.rpm

debian:

- new install usinb dpkg
  dpkg -i weewx_x.y.z.deb

- upgrade using dpkg take maintainer's version of weewx.conf
  dpkg -i weewx_r.s.t.deb
  modify /etc/weewx/weewx.conf
  dpkg -i weewx_x.y.z.deb

- upgrade using dpkg use old version of weewx.conf
  dpkg -i weewx_r.s.t.deb
  modify /etc/weewx/weewx.conf
  dpkg -i weewx_x.y.z.deb

- reconfigure using dpkg
  dpkg-reconfigure weewx

all platforms:

- installation and removal of extensions
  wee_extension --install cmon
  wee_extension --install pmon
  wee_extension --remove cmon

- reconfigure using wee_config
  wee_config --reconfigure
  wee_config --reconfigure --driver=weewx.drivers.vantage

- list drivers
  wee_config --list-drivers