#+TODO: TODO STARTED | DONE SKIPPED

Based on https://cdw.sourceforge.net/documentation/release_checklist/release_checklist.html


* DONE Review opened tickets

You may have some plans for current dev cycle, but take a look at opened
tickets. Maybe there is some high-priority ticket that needs to be included
in current dev cycle?

DONE:

This release will push forward the following tickets from GitHub:
https://github.com/acerion/cwdaemon/issues/12
https://github.com/acerion/cwdaemon/issues/10

This release will push forward the following internal tickets:
R0012
R0011

* DONE Define scope of changes to be done in this release

Describe them here, and stick to them during the development phase. Don't
extend the scope unless really necessary (e.g. unless you find a serious
bug).

If you plan to fix one of tickets from README.dev.org -> 'Bugs, feature
requests' list, put the ticket numbers on the list below.

The goals of this development cycle are:

** DONE Must-haves

*** DONE https://github.com/acerion/cwdaemon/issues/12
Fix it.

DONE in commit b26b10d39e13b4ea30b7a28e61a017dd8483c217

*** DONE Review and prioritize items from README.dev.org

See which items are critical.
Investigate, clarify and document unclear items.

*** DONE Quality of man page
Carefully review the man page. Fix typos, omissions, misinformations.

*** DONE fortify-source=2
Add it to compilation options. Fix issues triggered by this option.

DONE: -D_FORTIFY_SORUCE=2 has been added to CFLAGS in configure.ac. It is
used when compiling code of daemon and when compiling tests code.

There were no issues found when I ran my unattended functional tests. Some
issues may arise in the future, though.

*** DONE Basic tests with valgrind

Define scenarios, scripts, procedures needed to cover - in the long run - all
code paths with valgrind. The scenarios, scripts and procedures should be
easy to use in repeatable manner.

Use them at least once in this release. In this release we don't need to
cover 100% of code, but let's make a start.

DONE: functionality and fuzzing tests written in C accept "--supervisor"
option that can be set to "valgrind". When such option is passed to a test
binary, the test is executed against cwdaemon's instance running under
valgrind.

DONE: test scenario has been updated to include tests with valgrind.

*** DONE Basic tests with fuzzing of network socket

Define scenarios, scripts, procedures needed to cover with fuzzing - in the
long run - all code paths related to network socket. The scenarios, scripts
and procedures should be easy to use in repeatable manner.

Use them at least once in this release. In this release we don't need to
cover 100% of the network socket code, but let's make a start.

DONE: tests/fuzzing/simple/test_program has been created, and it has already
proved to be useful.

DONE: test scenarios document in qa/test_scenarios/ has been updated with
instruction to run fuzzing tests.

DONE: created ticket R0019 and R0020 to continue working on fuzzing in the
future.

*** DONE R0012: Static code analysis with clang-tidy

Port .clang-tidy and qa/lint_clang_tidy.sh from unixcw. Start using it
instead of current qa/clang_tidy.sh script. Fix a bunch of issues reported by
clang-tidy, but don't try to fix them all just yet. You can leave something
for next release.

DONE on 2024.02.11. I think that I addressed the most important issues. There
are still some excluded tests in .clang-tidy, and there are still some
warnings reported by clang-tidy (and by compiler), but I'm leaving the
warnings for now (till next version of cwdaemon).

Notice that ticket R0012 in README.dev.org is still open, to be revisited in
future versions of cwdaemon.

** DONE Nice-to-haves
*** DONE https://github.com/acerion/cwdaemon/issues/10
Understand it better. Fix if necessary.

DONE: there is nothing to fix. Problem reported in the ticket was caused by a
driver, not by cwdaemon. The github ticket has been closed without any
further action on my part.

*** DONE R0011: move forward with the ticket by fixing/adjusting just one more option

Do this slowly, one option at a time. The processing of command-line options
functions correctly so don't try to adjust everything at once and
accidentally break something.

DONE: options addressed in this release:
 - 'h'/"help" (print help text)
 - 'p'/"port" (network port on which cwdaemon listens)
 - 'I'/"libcwflags" (libcw debug flags)
 - 'y'/"verbosity" (verbosity threshold for debug messages)

*** DONE Unit tests

Try to find some nice small function or two that is easy to unit-test. Add
unit tests for the function(s) to cwdaemon test suite.

DONE: unit tests have been added for following code that existed in 0.12.0:
 - cwdaemon_get_long() function,
 - cwdaemon_option_network_port() function,

* SKIPPED Add -Werror to CFLAGS
During development phase you don't want to introduce any issues that can be
caught by compiler. -Werror will make sure that you will fix them before they
slip into repo.

Skipped. cwdaemon code base is not ready yet for -Werror.

* DONE Review 'terminology'

Refresh your knowledge of terminology and conventions for code and
documentation by reading the related section in README.dev.org.

Do this in order to avoid introducing non-compliant changes in code or
documentation.

* DONE Review 'lessons learned'

The previous development cycle may have happened a long time ago, and you may
have forgotten the lessons learned during the previous development cycle.

Refresh the lessons now to avoid making the same mistakes that you made in
the past.

Try to read the lessons learned few times during current development cycle.

* DONE Do the main work: implement release goals

Do whatever you planned to do for given release (see first point in this
document).

* DONE Stop the work on release goals

Regardless of what you did: fixing bugs, refactoring, adding features,
reviewing code, you need to be able to say "This is where I need to stop".
Constant making changes in code won't help you "freeze" your code and make a
release.

* DONE Review changes - quality check

Review changes in code, documentation and other files to catch and fix
problems, and to do last-minute necessary minor improvements.

Review all changes done since previous release.

Update comments and other documentation.

Update @reviewed_on tags in functions' top-level comments while doing the
review.

Don't be afraid to do refactoring if you notice opportunities or necessity to
do so.

Try to fix problems that you find during the review - especially those that
may affect end user.

Note down (as "tickets" in README.dev.org or as TODO/FIXME notes in code) any
problems that won't be fixed in this release.

* DONE Static code analysis

TODO: some functionalities in the package are disabled by default (mostly the
debug functionalities). You may want to enable them through ./configure
before running the static analysis.

These checks should be a part of Continuous Integration pipeline, but:
1. they are not (yet) (TODO: make them part of CI),
2. an additional 'manual' check of results should ensure that no serious
   issues have crept in.

** DONE clang-tidy

Use "run-clang-tidy" wrapper program (should be installed from some Linux
package). The wrapper will use .clang-tidy config file present in package's
root dir.

"bear" program should be installed from a Linux package.

1. Prepare the project's source code package for clang-tidy: configure it and
   build compilation database:

    ./configure --enable-dev-receiver-test --enable-dev-libcw-debugging --enable-dev-pcm-samples-file
    bear -- make && bear --append -- make check

2. Run clang-tidy:

    ./qa/lint_clang_tidy.sh <path>

3. Fix reported issues.

** SKIPPED cppcheck

Use ./qa/lint_cppcheck.sh script to run cppcheck. The script passes some
options to cppcheck.

"bear" program should be installed from a Linux package.

1. Prepare the project's source code package for validation: configure it and
   build compilation database:

    ./configure --enable-dev-receiver-test --enable-dev-libcw-debugging --enable-dev-pcm-samples-file
    bear -- make && bear --append -- make check

2. Run cppcheck:

    ./qa/lint_cppcheck.sh

3. Fix reported issues.

SKIPPED: cppcheck linting is not yet implemented.

* DONE Confirm that "make dist" and "make distcheck" works
** DONE "make dist"

1. Run "make distclean" in main directory of repo.
2. Run "autoreconf && automake && ./configure" in main directory of repo.
3. Run "make dist" in main directory of repo.
4. If "make dist" fails to build a release archive, fix the problems, and go
   to #1.
5. Confirm that there are no unnecessary files in release archive. If there
   are, fix the problem and go to #1.
6. Confirm that all necessary files (e.g. READMEs, examples, tests) are
   present in release archive. If any file is missing, fix the problem and go
   to #1.

** DONE "make distcheck"

1. Run "make distcheck" in main dir of repo.
2. If "make distcheck" fails to build a release archive, fix the problems,
   and restart this entire top-level bullet point by re-testing "make dist"
   first.
3. If "make distcheck" fails to compile code from release archive, fix the
   problem and restart this entire top-level bullet point by re-testing "make
   dist" first.
4. If "make distcheck" fails to successfully execute unit or functionality
   tests, fix the problem and restart this entire top-level bullet point by
   re-testing "make dist" first.
5. Re-run steps 1-4, but this time with the following change:

   Export options that will be used by ./configure executed during "make
   distcheck":

   export DISTCHECK_CONFIGURE_FLAGS="--enable-functional-tests"

   See
   https://www.gnu.org/software/automake/manual/html_node/Checking-the-Distribution.html
   for more info.

* DONE Come up with new version number
Based on scope of changes that you did, come up with new version number of
the package.

** DONE Update the package number throughout the repo
 - configure.ac/AC_INIT
 - NEWS + README + INSTALL files
 - ./qa/build_debian_packages.sh/VERSION
 - man page

** DONE Build Debian packages

Use a script for building Debian package (qa/build_debian_packages.sh) to
catch places that weren't updated correctly.

Inspect the built .deb package and auxiliary files, confirm that version
number on the package and files are correct.

* DONE Synchronize with Debian
** DONE Get *debian.tar.xz archive

Go to https://packages.debian.org/sid/cwdaemon, Download *debian.tar.xz archive.

** DONE Evaluate patches from the archive

You may want to apply them to the package. Update NEWS file with information
that the patches were applied. This will let Debian team know about it
because it may affect their workflow.

DONE: patches have been evaluated.

** DONE Merge debian/

Merge current version of files from debian/ dir in the archive into project's
repo. Let the configuration of the package in the repo be in sync with
Debian.

** DONE Run qa/build_debian_packages.sh

Run qa/build_debian_packages.sh to confirm that Debian packages can be built
more or less correctly. Fix any issues you will find.

DONE: lintian reports only those two items:
E: cwdaemon: depends-on-obsolete-package Depends: lsb-base (>= 3.0-6)
W: cwdaemon: missing-systemd-service-for-init.d-script cwdaemon [etc/init.d/cwdaemon]

** DONE Fix compiler warnings

While running qa/build_debian_packages.sh, pay attention to compiler
warnings. Debian's build scripts may use different complier flags.

DONE: the compilation reported no errors or warnings that weren't already
known.

* DONE Update info about dependency on unixcw/libcw

Update INSTALL file with details about required unixcw/libcw versions.

* DONE New test scenarios document

Make a properly named copy of qa/test_scenarios/template.org. The name of the
copy should reflect new version number of the package.

* SKIPPED Remove -Werror from CFLAGS
At this stage of this list there should be no more changes in code. Remove
-Werror from CFLAGS because after this stage there should be no occasions on
which you would introduce problems in code.

You don't want to have -Werror in code that you release: computers on which
this code will be compiled by your users may have different version of
compiler, and that compiler may discover some issues. You don't want to break
compilation on users' computers due to -Werror.

SKIPPED: the flag was not added to CFLAGS in the first place - source code of
cwdaemon is not ready for that yet.

* DONE Make sure that debug and optimization compiler flags are correct

Make sure that CFLAGS of code that is almost ready for release doesn't
contain "-g -O0". Do this before testing phase so that the code that you test
has been compiled with options similar to options used for release.

* DONE Do the testing per test scenarios

Test your software using test scenarios that you have created. See if you
need to repeat some tests on different software/hardware platforms. Write
down bugs that you have found and fixed, you may want to check for them when
testing next release, to see if you haven't reintroduced them.

* DONE Make sure that debug and optimization compiler flags are correct (again)

Make sure that CFLAGS of code that is almost ready for release doesn't
contain "-O0". Do this test for a second time (after testing phase): maybe
you have added the flags during fixing of some issues found during testing
phase.

* DONE Review the opened tickets, find fixed ones

Review the list of opened tickets from README.dev.org -> "Bugs, feature
requests". It may happen that some of them have been fixed during your work
in this development cycle, but you didn't notice it.

Read the list of opened tickets, find the tickets that describe already fixed
bug or already implemented feature, and close them.

* DONE Review descriptions of changes

Review information about what was changed in current releases:
 - NEWS file
 - ChangeLog file
 - README file
 - man page files (there may be several man pages, check them all)

Make sure that:
 - the information is factually correct,
 - the sentences and paragraphs are logically correct.
 - the structures of documents are valid.

* DONE Review initial scope of the release

Some items from initial scope of the release may not have been implemented
for one reason or another.

Review the unimplemented items. If any items are still valid, add them as
tickets to project's list of tickets - you don't want to forget about those
goals!

* DONE Run a spell check on documentation

Spell-check user-facing files:
 - NEWS
 - README
 - ChangeLog
 - man page files (there may be several man pages, check them all)

* SKIPPED Localization

If you use gettext or any other tool to facilitate localization of your
application then generate new file with strings intended for translation,
spell check it, make sure that all cryptic strings have explanatory comment,
re-generate the file again if needed.

I'm using gettext and friends in cdw, and I have prepared a small script that
invokes xgettext, the script is:

    #!/bin/bash
    xgettext src/*.c src/external_tools/*.c --no-wrap --keyword=_ --keyword=gettext_noop --add-comments=2TRANS: -o po/cdw.pot

All translatable strings are called by "gettext_noop()" or "_()" functions
("_()" is just an alias for "gettext()").



SKIPPED: cwdaemon doesn't use localization

* DONE Update your website files

If your project has a homepage, update content of website files so that the
website informs visitors about new release, latest changes and new features.
Do this now, you may want to reuse some content from files updated later
point. Test your website offline if you can. Don't put updated website files
online yet, there is still some testing to do.

Make sure that contact information available on your website is correct.

* DONE Update date in copyright notices

Update date (year) in the copyright statements like this one in all relevant
files:

    Copyright (C) 2011-2021  John Doe (email@domain.com)

* DONE Prepare release archive

Prepare tar.gz archive with source code tree that you want to release and
distribute. If you are using Autotools check "make dist" target, it is very
convenient.

DONE:
1. export DISTCHECK_CONFIGURE_FLAGS=--enable-functional-tests
2. make distcheck
3. tests are completed:

   PASS: unit_tests/daemon_utils
PASS: unit_tests/daemon_options
PASS: unit_tests/daemon_sleep
PASS: unit_tests/tests_random
PASS: unit_tests/tests_string_utils
PASS: unit_tests/tests_time_utils
PASS: unit_tests/tests_morse_receiver
PASS: unit_tests/tests_events
PASS: functional_tests/unattended/option_cwdevice_tty_lines/test_program
PASS: functional_tests/unattended/option_port/test_program
PASS: functional_tests/unattended/reset_register_callback/test_program
PASS: functional_tests/unattended/request_caret/test_program
PASS: functional_tests/unattended/request_esc_exit/test_program
PASS: functional_tests/unattended/request_esc_cwdevice/test_program
PASS: functional_tests/unattended/request_esc_reply/test_program
PASS: functional_tests/unattended/request_plain/test_program
============================================================================
Testsuite summary for cwdaemon 0.13.0
============================================================================
# TOTAL: 16
# PASS:  16
# SKIP:  0
# XFAIL: 0
# FAIL:  0
# XPASS: 0
# ERROR: 0
============================================================================

4. archive is built:
=================================================
cwdaemon-0.13.0 archives ready for distribution:
cwdaemon-0.13.0.tar.gz
=================================================



So it's possible to build a self-contained release archive.

However the archive won't be used anywhere since I no longer use SourceForge
for cwdaemon.

* DONE Make final test using code from release archive

  1. extract the archive in some temporary directory, outside of your regular
     development directory;

  2. make a standard build using extracted source code tree, just as any
     regular user would do;

  3. if your program has any unit tests that can be run by user, run them and
     make sure that all tests are passed;

  4. run the program that you have just built, check that program starts
     correctly, that all basic functions are running as expected, that there
     is no crash or error that would discourage user who is checking your
     program;


DONE: the steps from previous checklist point are showing how export && "make
check" are used to prepare and test the code.

* DONE Make final sanity check test using code from repository

  1. do an anonymous checkout of full source code tree from source code
     management (SCM) repository. This is to check if your SCM repository is
     accessible to regular users.

  2. make a standard build using checked out source code tree, just as any
     regular user would do. This is to make sure that build process will be
     successful: that there are no source code files or build system files
     missing in repository.

  You don't have to run tests or run the software and check if it works
  correctly here. You have already did this in point 12, and code in SCM
  should be the same as in your release archive.

DONE:
1. export DISTCHECK_CONFIGURE_FLAGS=--enable-functional-tests
2. make distcheck
3. tests are completed successfully
4. release archive is built successfully

* DONE Update statuses of issues in issue tracker

If you run any sort of bug or issue tracker, or feature request list, and
there are any issues affected or addressed by current release, update
statuses of these items: close them, comment them, update them. Don't let
fixed bugs be still open in your bug tracking system.

DONE: some tickets on GitHub have been updated

* SKIPPED Publish your release archive with your program

Whether you are using sourceforge.net, tigris.org, Alioth, your own website,
or any other means of publishing archive with your program, publish an
archive file with source code of your software.

SKIPPED: I no longer use SourceForge for cwdaemon, so there is no place in
which I could publish the release archive.

* DONE Tag release in SCM repository

Use git's annotated tag:
   git tag -a <tag-name> -m <tagging message>
   e.g.
   git tag -a v0.13.0 -m "Tagging release v0.13.0"


Don't forget to push the tag to remote:
   git push origin <tag-name>
   or
   git push origin --tags

This is a bit of a chicken-and-egg situation: if you tag first and then mark
this item as DONE, then the tagged commit won't represent a fully closed
release. But if you change this item to DONE and only then tag a commit, you
will claim that an item is DONE before it's done :)

The decision on how to solve the issue is: first mark this item as DONE, then
commit the change, and then tag the commit.

* DONE Update your website

Now that archive with program is available, you can publish your updated
website as well. Test the website to make sure that all pages are accessible.

DONE: cwdaemon.sf.net and related pages at sf.net have been updated with
information that cwdaemon has been completely migrated to GitHub.

GitHub page won't require any dedicated actions to update information about
the project's release.

