Build quilkin-filter-example as part of CI

[markmandel]

Looking at this example, and upcoming refactoring to API surfaces, I think it would be good to compile this example and make sure the code is not broken in CI (basically in make test).

I do note that the dependency is listed as quilkin = "0.1.0", and as such won't pickup new changes - but we could point it to local, much like we do on the macros crate.

@iffyio any reason you can think that would be a bad idea? (Since you wrote the example).

Only thought I had - we should make sure the examples link in our docs always points to a release branch, rather than main.

[iffyio]

SGTM!

[XAMPPRocky]

I'm not sure which is better but I think this should either be added as to [[examples]] in the Cargo.toml, or added as full workspace member to members. So that it is integrated and visible to Cargo.

Only thought I had - we should make sure the examples link in our docs always points to a release branch, rather than main.

I'm not sure about this, at least I have two main concerns about this approach.

• As you mentioned in Add mdbook and GitHub pages deployment #319 this would mean that links in examples to unreleased APIs would always be invalid until the release happens. This would prevent us from being able to use tooling like mdbook-linkcheck to check external links in CI. We could not check external links, which would be less than ideal in my opinion compared to being able to know all links work.
• If we pointed it at a specific the release branch, these links overtime will point to older documentation if not regularly updated, giving the user a very confusing experience if there's any significant differences between the versions. To prevent that we'd to have a latest branch or equivalent that always points to the latest released version, which would be more work than linking to main directly.

[markmandel]

As you mentioned in Add mdbook and GitHub pages deployment #319 this would mean that links in examples to unreleased APIs would always be invalid until the release happens.

Yeah this is a fun problem - and 100% agree, it would be good to check that all links work. The way I've handled this with other doc systems is that the branch name for a generalised link to github is dynamic. When running locally or pushing to the "latest" documentation, it's main. When doing a release push, it gets switched to release.x.y.z - can we do that with mdbook?

If we pointed it at a specific the release branch, these links overtime will point to older documentation if not regularly updated, giving the user a very confusing experience if there's any significant differences between the versions.

Absolutely. Same point above, if we have this coordinated via a central version number that stored in a config file that powers the generation of mdbook, then we can update this number as part of the release checklist (this is what we do for Agones).

My goal for aiming at a release branch is that if a used is working on 0.1.0 and get linked to examples in main (rather than the corresponding release branch), and the API surface has changed, that will also be confusing, as the examples won't line up with the documentation.

meta, meta note: I shouldn't make comments about docs in an issue is about CI 😁