Update release notes and add script to update version

[nehayward]

What does this pull request do?
This adds a little script to update the version number. The Release.md was updated as well

Checklist

• Documentation (if applicable)

closes #117

[zpatrick]

Can you please do this for each location mentioned in the release docs?

Also, given this can probably be done in a handful of lines, how about we try putting this into a new target in the top-level Makefile instead of adding a new file into /scripts?

[zpatrick]

Also, this doesn't close #117 since it's only addressing part of that issue.

[nehayward]

@zpatrick I will add that part in too.

[zpatrick]

We should have the team chime in, but I don't think we want/need to release the binaries on Github. We already have an easier pathway for users to download from S3 (because they can get the release for their specific OS), and adding that here just seems redundant and more code to maintain.

[zpatrick]

Another note, we don't want to run this in Travis. For one thing, Travis doesn't have the permissions to push to S3 or our Dockerhub account. Also, if we did go the Travis route for releases, we should run system tests first, which is a very large unit of work. Any Travis related stuff should be dropped from this PR imo.

[jparsons04]

For historical perspective, issue #117 has some previous discussion on this. An argument could be made to not have to depend on S3 hosting our releases and instead use built in GitHub functionality for delivering releases.

[tlake]

Oooh, great point about travis' permissions - I hadn't even thought about that.

As for releasing binaries on GitHub in addition to our docs, I'm sort of on the fence. I think that if we do release on GitHub as well, we should definitely break it up by OS in the same way we do in the docs. But whether or not we should do that... I don't know just yet. I like the idea of having binary releases so strongly coupled to the tagged version notes; I think that it's a good pattern found in a lot of other OSS repositories. It is redundant, though, given that we also link to binaries stored in S3 in our docs. Maybe the release process could be that the version notes on GitHub and the download links in our docs both link to the same source of binaries?

I guess what I like about releasing binaries on GitHub is that we're not tied to AWS resources paid for by IQVIA - if anything goes south and we lose access to those resources, our OSS tool is unaffected and still available on GitHub.

[nehayward]

Great thoughts everyone, just to clarify with the deploy portion.
It'd only be building the binaries the current layer0.ims.io/#download which can be done on in travis.

As far as s3 and DockerHub go we can continue to do that locally or figure out if it can be deployed via travis, which I believe can be done, ie https://docs.travis-ci.com/user/deployment/s3/

[zpatrick]

I guess my concern is more about releasing in multiple locations. To tlake's point, releasing on Github makes a lot of sense, and if we went that route, I'd like to see the S3 stuff go away.

[zpatrick]

If we are to keep the Github binaries, this should run at the end of the existing release target.
This can be accomplished in one or two lines, because all of the binaries exist in layer0/build by the end of that target.

[zpatrick]

This would break our versioning, this must be reverted back. Remember, we run this all the time, not just on "clean" releases like v0.10.4, but also on working branches where the version may be some long hash that includes the v character.

[zpatrick]

This should be taken out - it would execute every time we ran make, regardless of the target. Also, we don't want a dependency on .10 since that will change in the future.

[zpatrick]

Updating the docs' version references should be handled in a release target in layer0/docs-src/Makefile.

For example, in layer0/Makefile:

release:
        $(MAKE) -C api release
        $(MAKE) -C cli release
        $(MAKE) -C docs release                     <- added here
        $(MAKE) -C runner release
        $(MAKE) -C setup release
        $(MAKE) -C plugins/terraform release

        rm -rf build
        ...

and in layer0/docs-src/Makefile

build:
        mkdocs build --clean

release:
    # sed commands ...
    $(MAKE) build

[zpatrick]

KISS!!

We already have a release process that, aside from git housekeeping, works with a single command:

make release

Let's try to keep it that way unless we absolutely can't.

[zpatrick]

As stated above, this should already run as part of the top-level make release (something we should have done in the past, but would be a nice addition to this changeset).

[zpatrick]

Shouldn't we cut out this paragraph since make release will do that for us?

[zpatrick]

rebase and merge is preferred, if possible

[zpatrick]

These older versions don't exist right now - do we have a way to put them on github?

[nehayward]

Yes it's possible and I will add them before closing this.

[diemonster]

I don't think there's any value is having the older versions pre-v0.10 posted

[nehayward]

@diemonster I'll remove them.

[zpatrick]

Not sure why this is hardcoded to v0.10.4; see my comment below about possibly using templates to solve this.

[zpatrick]

For README.md, I think using sed along with stripping the v prefix is fine - however - don't reassign L0_VERSION: I worry that using the stripped version could cause inconsistencies with links and possibly other references we aren't seeing.

I think we should consider using a tool like expenv which replaces environment variables in template files. That way, we could add templated files, e.g. docs-src/index.md.template that contained:

...
## Download
| Download **$L0_VERSION** | |
...

and in this Makefile, we would have:

expenv -f docs/index.md.template > docs/index.md

For the problem of adding a new table entry, we could add a new template, reverse the order of our table, and use the append >> function:

expenv -f docs/release_table.template >> docs/releases.md

[nehayward]

Okay sweet, I was wondering about using a template file but wasn't sure if the added resources would be wanted. I'll switch to this.

[zpatrick]

not sure why macOS is the only non-capitalized name

[nehayward]

That's just how they name their OS's. like iOS, tvOS, etc.

[zpatrick]

I assume this file should be removed?

[nehayward]

Yup, missed that.

[zpatrick]

Why is this being deleted?

[nehayward]

It seems redundant. I can bring it back, but I migrated all the notes to Github

[zpatrick]

Ah cool, didn't realize that 👍

[zpatrick]

i dont think this is required

[nehayward]

I needed it for the expenv, otherwise the env wasn't being found. Not sure if it's a bug or something I did wrong.

[zpatrick]

since, from our convo below, expenv commands will be using L0_VERSION instead of L0_VERSION-V, I think this can be removed?

[zpatrick]

See my last comment -> README.md is the only place it is ok to use the stripped version, because we know it's specifically for the badge link. We don't want/need a template for README.md, so the sed should be done in place.

As I said before, any other replacements need to be done with the untouched L0_VERSION variable.

[nehayward]

Okay. Thanks for clarifying I'll fix this.

[zpatrick]

This regex needs to be something like v[0-9]+.[0-9]+.[0-9]+

-> v<1 to many ints>.<1 to many ints>.<1 to many ints>- e.g. v111.2222.33333 is perfectly valid.

[zpatrick]

this should be removed -> can use sed for this instance.

[nehayward]

👍

[zpatrick]

why is v0.10.4 hardcoded in the template?

[nehayward]

Hmmm 😕 I need to fix that. I thought I checked this file out before I pushed it.

[jparsons04]

I'm not sure how this happened if it was autogenerated, but somehow the .zip extension is missing from this link.

[nehayward]

Good catch. I'm not sure what happened I'll check that the autogen is still working

[nehayward]

Needed for expenv

[zpatrick]

This regex needs to be something like v[0-9]+.[0-9]+.[0-9]+

-> v<1 to many ints>.<1 to many ints>.<1 to many ints>- e.g. v111.2222.33333 is perfectly valid.

[zpatrick]

need to remove extra hash on the end

[nehayward]

✅

[zpatrick]

regex needs updated (see previous comment)

[jparsons04]

Do we want to run the script now so that references to 0.10.4 like here and elsewhere update the version to 0.10.5?

[nehayward]

Yeah I could do that now. It'll make the merge easier.