add maintainer docs and Cargo.lock

[davepacheco]

This PR:

• adds docs for maintainers that cover publishing a new release and our use of Dependabot
• adds Cargo.lock, as recommended by @cbiffle (and documents why we do it)
• updates CI to enforce that Cargo.lock is correct by building with --locked.

If the Cargo.lock check-in is controversial, I can do that in a separate PR. It's here because I thought I'd already done it, so I documented it, and then realized that I hadn't actually done it yet, and it didn't seem worth splitting out.

CC @ahl @smklein. I think there are probably too many words here, but I wanted to err on the side of more docs rather than less.

[smklein]

Earlier we made the assertion the following regarding Lockfiles:

Since the CI tests always run against a particular commit, this allows us to know exactly which dependencies were used for a particular CI run. It also communicates to consumers what we've tested.

If dependabot can update Cargo.toml files without updating Cargo.lock files, hasn't this assertion been broken? If dependabot updates a rev, but Cargo.lock is left out of date, then won't CI runs be inconsistent?

If we need to add the caveat that "Cargo.lock shows what dependencies are used, unless dependabot changed something, in which case it might be out-of-date", IMO the value of keeping a lockfile around drops significantly.

[davepacheco]

Yeah, that's a good point. Better options here are probably:

• don't check in Cargo.lock
• point dependabot at the whole workspace and treat it like an application
• point dependabot at the whole workspace and try to configure it to treat it like a library. This seems best to me, but I'm not super optimistic based on the quality of the docs and the time I spent reverse engineering this last time.

[davepacheco]

It turns out that the docs are actually correct:

The property '#/updates/0/versioning-strategy' value "increase-if-necessary" did not match one of the following values: lockfile-only, auto

From looking at the source a few weeks ago, the "auto" option decides whether it's an app or a library based on the presence of Cargo.lock (Cargo.lock present => application). So if we use "auto", dropshot will be treated like an application, which means dependabot will be somewhat aggressive about updating dependencies. If we chose "lockfile-only", I believe it would bump Cargo.lock as compatible updates to dependencies were published, but never update Cargo.toml (which largely defeats the point).

I think I'd like to try letting dependabot treat dropshot like an application. The downside is that if we have a dep version like 1.2.3, and 1.3 comes out, it will update Cargo.toml to specify 1.3, even though we might be fine with 1.2.3 and 1.3, so we're imposing additional constraints on our consumers. I'm hopeful that we can avoid this problem by avoiding such specific dependencies in Cargo.toml unless we really need them. That is: if we leave our dep at 1.2, and 1.3 is compatible with that, dependabot won't update Cargo.toml. (I'd expect it to update Cargo.lock, and that's fine and probably useful.)

I've done this in 6f9adbd.

[smklein]

Since these two steps cancel each other out, why bother doing them? Doesn't the dry run provide enough information about what will happen?

[davepacheco]

If I were going to drop either the --dry-run step or the --skip-push --skip-publish step, I would skip the --dry-run because it doesn't provide any information over the other one. I believe I saw cases (while working out the config) where the dry run succeeded and the --skip-push --skip-publish failed.

I think what you're getting at (and I kind of alluded to later without saying it) is that there's a bunch of fear in this procedure. I think that fear stems from my initial experiments with cargo-release resulting in it doing things I found very surprising. I don't remember more than that, but the lesson I internalized was that I wanted to see exactly what it was doing before committing to anything. I expect others might not be so paranoid about it, which is why I started with the "if you're daring" one-liner, but kept in enough detail for somebody to do it very carefully if they wanted.

[smklein]

Ah, yeah, at first read I think I somehow missed that "if you want to go all-out, use this one liner" option. Makes sense to have a more intensive breakdown to see all the incremental changes, and then folks can rely on the shorthand once they (or the collective we) trust the process.

[smklein]

To make sure I'm understanding correctly: The crate is published before the commits are pushed? Is this because we're creating tags and publishing, but explicitly passing --skip-push?

Is there a reason we're avoiding letting cargo release do this for us?

[davepacheco]

That is correct. The reason is what I mentioned above: I wanted to be able to check the tool's output as much as possible before committing to it. Separating this allows one to check them before pushing. (Yes, we may have already published, but that's why I also do a the non-publishing version first, too.)

The one-liner at the top of this section has cargo release do it for you.

[smklein]

Thanks for the docs / updates!

[davepacheco]

I just sync'd this up, updated Cargo.lock, and fixed the docs for the Dependabot change I made (discussed above). I plan to land this shortly.