Tooling idea thread: Post ideas for things you would like to have. Could be heroku or rust specific or could be more general

[schneems]

(General) Keep a Changelog linting

We have changelog checking on GHA, but it doesn't validate the format. If we added Keep A Changelog linting it would prevent issues like https://github.com/heroku/buildpacks-ruby/pull/283/files#diff-82032714d881e3cbf53230847846645d5956738ab3ce7b30b839dac1f02fa934R10. A changelog entry is added, but it is not under an Added/Changed/Fixed header.

Possible solution(s):

• Extend the Changelog check to also validate the format and raise an error appropriately

(rust) Lint deny_unknown_fields used on all Deserialize structs

Info on the flag in heroku/buildpacks-ruby#272. It would be nice to have some way to lint/check this for Rust buildpack projects.

Possible solution(s):

• Some kind of lint to ensure all declared structs that are Deserialize also use this feature
• Documenting this caveat somewhere, such as a mdbook

(rust) Protect against logic errors for filesystem access

Problem: Some of the Rust stdlib functions can hide problems, for example https://doc.rust-lang.org/std/path/struct.Path.html#method.is_file will return false if there is a permissions error with a file. This results in confusing error messages to users because we might say something like "No such file Procfile, please add this file to your project and try again" but if they $ ls they'll see Procfile. The answer to this problem is to ensure APIs that return a Result are used instead like https://doc.rust-lang.org/std/path/struct.Path.html#method.try_exists.

Possible solution(s):

• Some kind of lint to check against using a known set of "bad" APIs and error on them.
• Documenting this caveat somewhere, such as a mdbook

Add your own ideas

Post below

[colincasey]

(General) Keep a Changelog linting

This seems like a job that https://github.com/heroku/keep_a_changelog would be well suited for. We could enhance that repo with some WASM compilation for use in a GitHub Action that handles validation and/or other checks.

(Rust) CNB semver checks

Imagine something like cargo-semver-checks but it checks rules like the ones defined in Paketo's Semantic Versioning of Buildpacks and Builders RFC against libcnb.rs-based projects.

[schneems]

A place to put recommended best practices and tools that help achieve them. Including (but not limited to) checklists and descriptions for why they exist. For example:

Command execution best practices

Checklist

• An exact representation of the command being run should appear in logs, or the error, or both
• Make non-zero status an error
• If a command representation is output to the logs, changes to the command should be visible in the output (the display and command being run should come from a single point of truth).
• Stdout and Stderr from the command should appear in logs, or the error, but NOT both (if it runs).
• Stream output or print a progress indicator for commands that may take awhile or that access the network

Tooling

• https://crates.io/crates/fun_run
• https://crates.io/crates/bullet_stream

Why

• An exact representation of the command being run should appear in logs, or the error, or both

When a command fails, any flags or arguments being used may be needed to reproduce the failure. If the full command is output to the log before execution, then it's not needed in the error (but not a problem if there's duplication since commands are generally not overwhelmingly large). If it's a shortened command that's output to the logs or being used as an internal-only tool that's not output at all, then the full command should appear in the error. Easiest/best practice is to always include the EXACT command that was run in any error messages produced by failing commands.

• Make non-zero status an error

By default Rust will only return an Err on a "systems" problem. This type of error mostly occurs when the operating system could not find a binary on the PATH to execute. When the command runs, the status needs to be checked and and error raised if it's not 0 (indicating success).

• If a command representation is output to the logs, changes to the command should be visible in the output (the display and command being run should come from a single point of truth).

Printing commands and including them in error messages is intended to help buildpack users and maintainers debug. If the value output is different than what's being run, then it's a time consuming and difficult process to figure out that's the case. By using only a single source of truth (the command being executed) any modifications to that command will automatically be picked up in error messages.

• Stdout and Stderr from the command should appear in logs, or the error, but NOT both (if it runs).

Commands can produce warnings and error messages. If stdout and stderr are not visible, then those messages are not seen. These outputs can be quite large, so if the command is already being streamed to the build output, then the error can simply highlight that the contents are visible above. If not, the contents should be included in the error message incase there's a relevant warning or error message.

• Stream output or print a progress indicator for commands that may take awhile or that access the network

As developers, we sometimes forget that our home-offices with Gigabit internet are not indicicative of all user experiences. Because CNBs have a local component, they may be run on flaky WIFI at hotels etc. What might take less than one second at home might take a minute or more while traveling. It's best practice to let people know that the buildpack is still working and didn't die by either streaming the in-progress logs of the command, or printing a background indicator (like dots) while the user waits for the command to finish.

Examples

• list
• of
• links
• to
• IRL
• examples