Update nannou-new to work with cargo workspaces

[mitchmindtree]

This could be done by first checking for a Cargo.toml containing a [workspace]. If one is found, it could be updated to include the new crate before the directory is created.

[kneitinger]

Interestingly enough, workspaces have broken nannou-new.

In d6d5d38, the examples directory was moved from nannou/nannou/examples (the nannou package in the nannou repo) to nannou/examples - its own package in the repo.

In addition to nannou-new not being able to find template_app.rs and template_sketch.rs because of their new location, there is another issue, which I cannot figure out how to fix just in code.

---

(note: the hypothetical steps in following description do not match nannou-new's current code, since it's current approach of grabbing the most recent nannou crate to both figure out version and grab the templates, can no longer be used)

The problem stems with the lack of versioning on the repo as a whole. Say we query crates.io to find the most up to date nannou release so that we can make an entry in our new project's Cargo.toml. That works fine, and we now know we're targeting 0.14.1. Now how do we find the relevant templates? We cannot use cargo since the examples crate is rightfully unpublished.

At this point we have to grab it from github directly, which I think is acceptable, however, there is currently not a way to determine the proper version of the template file to grab.

If we naively clone the examples/templates/template_app.rs file from master, we run the risk of generating projects that do not compile. For example, if the template app file is modified to include an exciting new feature that hasn't hit crates.io yet.

Currently, the nannou repo does not use any tagging or releases. This means that it is very difficult to correlate a version published on crates.io to the commit at which it was created.

---

What I see as the best solution (but I'm sure there are plenty that I haven't thought of) is for this repo to start tagging commits that are pushed to crates.

Because this repo is organized as a workspace, the semantics of tags are not perfectly obvious, but two solutions could work out well:

1. Create a tag for every version of the nannou crate, since it arguably impacts most every crate. So for instance, if nannou 0.14.2 came from commit 39c9ed, then the git tag 0.14.2 or v0.14.2 would point to that commit. This is pretty low maintenance, but might be confusing to have a workspace versioned in such a way.
2. Create a tag for every published version increase of every crate. In this case, we could do what was describe for nannou in the last list item, but name the tags nannou_0.14.2, nannou_laser_0.15.0, etc. This method is more clean, but should really be handled with automation.

Having the tags means that nannou-new can pull the template_app.rs and template_sketch.rs files that perfectly correspond to the most recent nannou version on crates.io.

---

What are your thoughts? What feels like something we could get implemented so that the nannou-new refactor can progress? Sorry for the wall of text!

[kneitinger]

Another option is to move the template files to the nannou_new package so that they're distributed with that application.

This is by far the easiest to implement and requires no release workflow or repo organizational changes, however, what I see as a downside to this approach is that the template files would no longer be in the examples directory.

examples feels like a great place for them, since new users are likely find them helpful as reference (I certainly did when I started out using Nannou), and they're much more likely to be kept up to date there than if they lived in a subdirectory of the nannou-new crate.

[mitchmindtree]

What I see as the best solution (but I'm sure there are plenty that I haven't thought of) is for this repo to start tagging commits that are pushed to crates.

Yes, agreed this sounds great!

We're careful to synchronise all the "breaking" version updates across all of the nannou libraries in the workspace. For example, nannou version 0.14.* should always be compatible with nannou_osc version 0.14.* and so on. There's a small program in scripts/set_version which aims to make this easy to do for maintainers.

Perhaps adding tags for these minor version updates (e.g. 0.14, 0.15, 0.16) would be enough, as the templates should always be compatible with all patch releases in the minor version?

I don't have any experience with git tags myself - is adding these retroactively something that can be done in a PR? Or will this require editing the git history? I imagine it might be the latter - if so let me know and I'll try to get around to this asap!

Sorry for the wall of text!

Don't be! I really appreciate the thought that's going into this :)

[kneitinger]

Scheme

Given that the breaking changes are accounted for, I think that a workspace-wide tag for every minor- version could work out well for this! Even if we're only tagging minor versions, I would advocate for the tags beingvMAJOR.MINOR.PATCH scheme for future-proofing. I still think there is generally some value in being able to correlate a crate.io release to a specific point in time, but that doesn't affect this and is something that could be done later if folks ever see a need for it.

Tags, GitHub and Releases

Ignoring GitHub for a moment, a tag simply marks a point in time. There is no code change or commit for a tag's creation, its basically a bookmark on a specific (existing) commit to say "hey this is a noteworthy moment in time"

GitHub, or at least GitHub's UI muddies the water a tiny bit. There is no ability to create a tag (even though there is a view for them), only a "release" (which in turn, creates a tag). I'll show the differences in the next section.

Process

Tags

The process is relatively simple from the command line, and can be done retroactively, however there is no ability to put them through an approval process such as a PR.

To tag from the command line:

$ git checkout master
$ git tag -a v0.14.0 857a7840b3e8ffb4eb81ac8cfe31a64dc36d307a
# enter short message in $EDITOR or use -m flag, just like git commit
# I entered "Retroactive test tagging of the v0.14.0 upgrade"
$ git show v0.14.0 
tag v0.14.0
Tagger: Kyle Kneitinger <kyle@kneit.in>
Date:   Tue Sep 29 17:28:01 2020 -0700

Retroactive test tagging of the v0.14.0 update

commit 857a7840b3e8ffb4eb81ac8cfe31a64dc36d307a (tag: v0.14.0, tag: v0.14)
Author: mitchmindtree <mitchell.nordine@gmail.com>
Date:   Fri Apr 24 12:42:21 2020 +0200

    Update all nannou crate versions to 0.14.
$ git push origin v0.14.0

I ran the following commands on my fork. Feel free to take a look, but when you're reading this, the pretend v0.15.0 "Release" will also be there.

If I go to my fork's tag listing by clicking here

We'll see that v0.14.0 tag I pushed

Curiously enough, we'll also see it in the Releases tab, but it is not what GitHub calls a release...it seems that they are displayed to give context to releases with regards to tags

Releases

As far as I know, a "release" is a github specific thing that associates a tag with a deliverable/artifact such as a compiled binary. (GitHub conveniently creates zip and tar.gz archives of every tag already).

A release is created from the "Draft a new release" button in the Release tab from last screenshot.

You can name the release, and create an associated tag (or use an existing one), and upload the artifacts

Once created, the releases tab looks like this:

That fake 0.15.0 release was created at my fork's master branch's HEAD. It also created the v0.15.0 tag in the Tags tab.

Reversibility

Both tags and releases can be deleted from GitHub, so there is no concern of pushing something that is irrevocable.

Recommendation

If you don't mind pushing directly from the command line, I feel that tags are sufficient and nicely minimal for the simple use-case.

[kneitinger]

@mitchmindtree thank you so much!

I have nannou_new working nicely again, with half of the dependencies as before (due to stripping the cargo crate for #606).

A nice side-effect of the tagging that I hadn't considered is that we can now access raw versioned files at URLs such as https://raw.githubusercontent.com/nannou-org/nannou/v0.14.0/examples/templates/template_app.rs. Instead of pulling all of the nannou repo, or even the examples dir, we can simply pull only the template file we need.