ttytm/wthrr-the-weathercrab

[Suggestion] Further Repository Utilities

kevinmatthes opened this issue · 2 comments

kevinmatthes commented

@tobealive

I would like to suggest to configure the following utilities for this repository:

  1. a version number incrementing system, like bump2version or cargo-release
  2. citation metadata such that Wthrr can be cited like a book
  3. issue forms
  4. a self-updating information on the code coverage in README.md
  5. mirroring README.md from the crate's root description, i.e. conditionally updating the README from a SPOT
  6. an almost self-maintaining CHANGELOG

Which of these points sound interesting for you?

ttytm commented

Thanks for the suggestions @kevinmatthes

  1. I don't think it's needed for this small app. Would be a yes if it was a larger app or a library.
    In regard to the noice this generates. A more organic as-good-as-possible semver versioning should be sufficient.

  2. Same as the first part of 1.

  3. Issue froms sound good :)

  4. There hasn't been a change in codecov since the ci was added, so the comment from the related issue still holds true.

    maybe hold off adding a coverage badge to the readme for the time being ;)
    #103 (comment)

  5. Would like to look into it to get a better opinion.

  6. More of a 'no' than a 'yes' for me. Currently, I don't mange to dedicate a lot of time to actively care for or develop the repository. If it is 'almost' self-maintaining and just adds a little overhead, even that I'm considering excessive given the circumstances. The GitHub-auto-generated changes, along with the potential manual edits required when making a release, feel sufficient.

kevinmatthes commented

Thank you for your feedback! Here are some additional information.

Point 5:

A crate's root can be documented using Rust's Markdown documentation comments. Anything you can render in the README dynamically will render in the crate root's documentation, as well, i.e. images and badges. When you edit the documentation of the code anyway, you will be more likely to edit the crate root's documentation than the README -- they might become out of sync although they are supposed to contain mostly the same information. You now set up a workflow which watches the crate root's source file on the default branch for changes; if the file was edited, the workflow will extract the documentation text, paste it in the README and submit a PR with the changes. The PR could also be empty. If you agree with the changes made by the workflow, you can merge it and thereby update the README.

The setup effort consists of putting the README text prefixed with //! per line into src/main.rs as this repository does not have a library root. The workflow is already configured in one of my repositories, I would just copy and paste it -- with the necessary changes, of course.

The interaction effort restricts to either merge or close the raised PR.

Point 6:

On PR, a user manually triggers a workflow on their branch (i.e., clicking a button in the Actions tab). The workflow will harvest the commit messages using a certain pattern (can be configured almost completely freely) and push a change report known as "fragment" to the branch it is called on. The fragment is stored in a central directory where all other fragments of the next version are saved, as well. On release, the maintainer manually triggers a workflow which will assemble all saved fragments and paste their sorted contents into the CHANGELOG file. The processed fragments will be deleted as they now have fulfilled their purpose. These changes are submitted as a PR. You can review them, check for correctness etc., and finally merge the PR to update your CHANGELOG.

The setup effort consists of two workflow files (fragment creation and collection), the CHANGELOG basic setup, and a configuration file which dictates how the CHANGELOG has to look. Setting up all of these things is routine for me.

The interaction effort consists of invoking the collection workflow, i.e., clicking a button in the Actions tab, as well as merging the submitted PR. You can even make it run without submitting a PR and pushing directly to the default branch but I highly recommend reviewing automated changes before applying them.

Both utilities are based on the same Rust binary which needs to be installed from the package registry. Compiling it from scratch takes about three minutes, so I recommend a cache. You can also install that binary on your local machine and run the steps there, this will save you from having to wait for the CI to finish every time.