Automate release process

[adbancroft]

This PR adds a GitHub action to prepare the code base for a release (updating the version number in various files) and generates a draft release with the appropriate tag.

Usage:

1. Manually run the 'Create draft release' workflow/action
2. Follow the output link to the created draft release. E.g.
   
3. Edit the release notes & publish

This codifies tribal knowledge & will avoid issues like #108

[kimwalisch]

@adbancroft Can you please add a RELEASE.md which explains the release procedure using e.g. a short list of bullet points. The goal of this file should be that new maintainers can easily figure out how to do a new release without any help needed from previous maintainers (since they might not be around anymore).

[kimwalisch]

In my opinion it would also be better to hardcode the version number of LIBDIVIDE_VERSION in libdivide.h and update it using your release script. Your macro string concatenation code is complicated, it might potentially cause problems when libdivide.h is imported into programming languages other than C/C++.

[adbancroft]

Your macro string concatenation code is complicated, it might potentially cause problems when libdivide.h is imported into programming languages other than C/C++.

• It's a very widely used C pre-processor technique: the GCC manual describes it at least as far back as v2.95 (released in 1999)
• I'd prefer to keep the code DRY - this seemed like the simplest approach.

Is there a specific use case you have in mind?

[kimwalisch]

Is there a specific use case you have in mind?

We should try to keep the libdivide.h code as simple as possible and only add additional complexity if this improves libdivide.h in a meaningful way (e.g. improves performance). If I understand your pull request correctly then it is possible to move the complicated code related to the LIBDIVIDE_VERSION macro into your release script which would allow to get rid of all your string concatenation macros.

It's a very widely used C pre-processor technique: the GCC manual describes it at least as far back as v2.95 (released in 1999)

You as proficient C/C++ programmer might easily understand this code. But many other programmers will not immediately understand this code. So why add this complexity to libdivide.h when there is a less complex alternative solution?

[adbancroft]

You as proficient C/C++ programmer might easily understand this code.

Hah!

In the interest of moving this PR, the version string is now directly embedded (same as current master).

I've also updated the docs: see doc/Developement_Guide.md (which is linked from ./readme.md). It has sections for building, testing, benchmarking, CI & releasing.

[kimwalisch]

I made some changes to your pull request:

• I added back some of the original doc from ridiculousfish to README.md. I think this doc is important and should be in the main README.md so that users can easily find this information (however we must be careful not to add to much detail about all possible build system settings to README.md, README.md should only contain the most important stuff).
• I created RELEASE.md instead of Development Guide.md.

But I still have some questions (I think we should also answer these questions in RELEASE.md):

• How does your code know what release type we want to do? E.g. let's suppose I make a breaking change and want to release a new major version, how does your code know that I want to release e.g. the version 6.0.0?
• Since you wrote all the AVR test code, ideally you should create a test directory in the libdivide root directory that contains all files related to tests. Currently we have a lot of files in the root directory that even I don't know what their use is. When new users visit libdivide I am sure they don't immediately understand that the only file they need in their project is libdivide.h. Ideally we should only have the most important files in the root directory.

[adbancroft]

How does your code know what release type we want to do? E.g. let's suppose I make a breaking change and want to release a new major version, how does your code know that I want to release e.g. the version 6.0.0?

You tell it when you run the workflow:

I updated release.md with this detail, though it should be self-explanatory when the workflow is run.

Since you wrote all the AVR test code, ideally you should create a test directory in the libdivide root directory that contains all files related to tests. Currently we have a lot of files in the root directory that even I don't know what their use is. When new users visit libdivide I am sure they don't immediately understand that the only file they need in their project is libdivide.h. Ideally we should only have the most important files in the root directory.

Almost all AVR test code is in test/avr, the only exception being avr_test.code-workspace. Let's address this in a separate PR/issue.

[adbancroft]

I made some changes to your pull request:

I added back some of the original doc from ridiculousfish to README.md. I think this doc is important and should be in the main README.md so that users can easily find this information.

I created RELEASE.md instead of Development Guide.md.

This:

• Deleted several corrections and additional pieces of information that would be useful for contributors. E.g. example cmake command lines, using ctest to run all tests, details on CI.
• Left a rather small `release.md' that has no incoming links.

(however we must be careful not to add to much detail about all possible build system settings to README.md, README.md should only contain the most important stuff)

Agreed. Which is why I was targeting readme.md for consumers of libdivide and a separate doc (Development_Guide.md) targeted at contributors to libdivide.

[ridiculousfish]

LOL, powershell! Seems fine to me.

[kimwalisch]

@adbancroft Thanks for your work!