style: Apply new formatting and add a CONTRIBUTING.md which explains it. (#381)

Co-authored-by: Dylan Anthony <[email protected]>

Author: dbanty

.github/workflows/tests.yml

@@ -39,6 +39,29 @@ jobs:
       - name: Test building the book
         run: cargo make book
 
+  check-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: |
+          rustup override set nightly
+          rustup update nightly
+          rustup component add rustfmt
+
+      - name: Install cargo-binstall
+        run: |
+          wget https://github.com/ryankurte/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-unknown-linux-musl.tgz
+          tar -xvf cargo-binstall-x86_64-unknown-linux-musl.tgz
+          cp cargo-binstall $HOME/.cargo/bin
+
+      - name: Install cargo-make
+        run: cargo-binstall --no-confirm cargo-make --force
+
+      - name: Install taplo
+        run: cargo-binstall --no-confirm taplo-cli --force
+
+      - run: cargo make check-format
+
   validate-config:
     name: Validate Knope Config
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Knope is open to all kinds of contributions—if you want to contribute code there are a few helpful hints.
+
+## cargo-make
+
+We use [`cargo-make`](https://sagiegurari.github.io/cargo-make/) to make running some development tasks easier. You do not _need_ `cargo-make`, but it is recommended. Here are the common tasks you'll want to run:
+
+1. `cargo make` will run all the development tasks, reformatting code, linting, and running tests.
+2. `cargo make serve-book` builds the docs, watches for changes, and starts a local webserver to view them.
+3. `cargo make ci-flow` will run _most_ of what CI does, excluding building the docs and checking formatting.
+4. `cargo make check-format` checks the formatting of the code the same way that CI will.
+
+## Formatting
+
+We use `rustfmt` to format Rust code, but we depend on unstable features (e.g., sorting imports). You need to install the nightly toolchain (e.g., `rustup toolchain install nightly`) before formatting the code.
+
+We also use [Prettier](https://prettier.io) to format Markdown (via [`npx`](https://docs.npmjs.com/cli/v7/commands/npx)) and [Taplo](https://crates.io/crates/taplo-cli) for formatting TOML. Taplo will be installed automatically if using `cargo-make`, but `npx` must be available to run Prettier.
+
+## Snapshot Tests
+
+We use [snapbox](https://crates.io/crates/snapbox) for most of the integration tests in the `tests` dir. This allows us to run commands end-to-end and compare the output to what we expect (making it much clearer when things change).
+
+The general workflow for a snapshot test is:
+
+1. Create a new directory in `tests` (optionally nested in a subdirectory relevant to what you're testing) which contains all the setup files you need (e.g., a `knope.toml` and a `Cargo.toml`).
+2. Create a temp directory and copy all the source files over.
+3. Use the functions from `tests/git_repo_helpers` to set up a git repo and add any commits/tags you need (for testing releases).
+4. Run the command and verify the output using snapbox.
+
+A good example of this is the `prerelease_after_release` test in `tests/prepare_release.rs`.

Makefile.toml

@@ -42,6 +42,18 @@ args = ["prettier", "**/*.md", "--list-different", "--prose-wrap=never"]
 command = "cargo"
 args = ["deny", "--all-features", "check"]
 
+[tasks.check-format-toml]
+install_crate = "taplo-cli"
+command = "taplo"
+args = ["format", "--check"]
+
+[tasks.check-format]
+toolchain = "nightly"
+dependencies = ["prettier-check", "check-format-toml"]
+
+[tasks.format]
+toolchain = "nightly"
+
 [tasks.dev-test-flow]
 dependencies = [
   "deny",
@@ -56,4 +68,4 @@ dependencies = [
 ]
 
 [tasks.pre-ci-flow]
-dependencies = ["deny", "clippy-flow", "check-format"]
+dependencies = ["deny", "clippy-flow"]

deny.toml

@@ -69,7 +69,15 @@ unlicensed = "deny"
 # List of explicitly allowed licenses
 # See https://spdx.org/licenses/ for list of possible licenses
 # [possible values: any SPDX 3.11 short identifier (+ optional exception)].
-allow = ["MIT", "Apache-2.0", "ISC", "OpenSSL", "MPL-2.0", "BSD-3-Clause", "Unicode-DFS-2016"]
+allow = [
+  "MIT",
+  "Apache-2.0",
+  "ISC",
+  "OpenSSL",
+  "MPL-2.0",
+  "BSD-3-Clause",
+  "Unicode-DFS-2016",
+]
 # List of explicitly disallowed licenses
 # See https://spdx.org/licenses/ for list of possible licenses
 # [possible values: any SPDX 3.11 short identifier (+ optional exception)].
@@ -163,7 +171,7 @@ skip = [
 # by default infinite
 skip-tree = [
   { name = "windows", version = "0.40.0", depth = 10 }, # Waiting on update to git-index
-  { name = "ahash", version = "0.7.6", depth = 10 },   # Waiting on update to hashbrown
+  { name = "ahash", version = "0.7.6", depth = 10 },    # Waiting on update to hashbrown
 ]
 
 # This section is considered when running `cargo deny check sources`.

docs/src/default_workflows.md

@@ -24,5 +24,5 @@ Without any config, you can run `knope release` to create a new release from [co
 
 [conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/
 [semantic version]: https://semver.org
-[`PrepareRelease`]: config/step/PrepareRelease.md
-[`Release`]: config/step/Release.md
+[`preparerelease`]: config/step/PrepareRelease.md
+[`release`]: config/step/Release.md

rustfmt.toml

@@ -0,0 +1,3 @@
+unstable_features = true
+group_imports = "StdExternalCrate"
+imports_granularity = "Crate"

src/app_config.rs

@@ -1,7 +1,6 @@
 use platform_dirs::AppDirs;
 
-use crate::prompt::get_input;
-use crate::step::StepError;
+use crate::{prompt::get_input, step::StepError};
 
 /// For managing configuration of knope globally
 

src/command.rs

@@ -3,11 +3,10 @@ use std::collections::HashMap;
 use execute::shell;
 use serde::{Deserialize, Serialize};
 
-use crate::git::branch_name_from_issue;
-use crate::releases::get_version;
-use crate::state::Release;
-use crate::step::StepError;
-use crate::{state, RunType, State};
+use crate::{
+    git::branch_name_from_issue, releases::get_version, state, state::Release, step::StepError,
+    RunType, State,
+};
 
 /// Describes a value that you can replace an arbitrary string with when running a command.
 #[derive(Debug, Deserialize, Serialize)]
@@ -99,9 +98,8 @@ fn replace_variables(
 mod test_run_command {
     use tempfile::NamedTempFile;
 
-    use crate::State;
-
     use super::*;
+    use crate::State;
 
     #[test]
     fn test() {
@@ -128,12 +126,14 @@ mod test_run_command {
 
 #[cfg(test)]
 mod test_replace_variables {
-    use crate::issues::Issue;
-    use crate::releases::{semver::Version, Package, Release};
-    use crate::state;
     use std::path::PathBuf;
 
     use super::*;
+    use crate::{
+        issues::Issue,
+        releases::{semver::Version, Package, Release},
+        state,
+    };
 
     fn packages() -> Vec<Package> {
         vec![Package {

src/config.rs

@@ -1,15 +1,15 @@
-use std::collections::BTreeMap;
-use std::fs;
-use std::path::PathBuf;
+use std::{collections::BTreeMap, fs, path::PathBuf};
 
 use miette::{IntoDiagnostic, Result, WrapErr};
 use serde::{Deserialize, Serialize};
 use velcro::{hash_map, vec};
 
-use crate::releases::find_packages;
-use crate::step::{PrepareRelease, Step, StepError};
-use crate::workflow::Workflow;
-use crate::{command, git, releases};
+use crate::{
+    command, git, releases,
+    releases::find_packages,
+    step::{PrepareRelease, Step, StepError},
+    workflow::Workflow,
+};
 
 #[derive(Deserialize, Debug, Serialize)]
 pub(crate) struct Config {

src/git.rs

@@ -1,16 +1,16 @@
-use std::path::PathBuf;
-use std::str::FromStr;
+use std::{path::PathBuf, str::FromStr};
 
-use git2::build::CheckoutBuilder;
-use git2::{Branch, BranchType, Repository};
+use git2::{build::CheckoutBuilder, Branch, BranchType, Repository};
 use log::{debug, error, trace, warn};
 
-use crate::issues::Issue;
-use crate::prompt::select;
-use crate::releases::{get_current_versions_from_tag, tag_name};
-use crate::state;
-use crate::step::StepError;
-use crate::RunType;
+use crate::{
+    issues::Issue,
+    prompt::select,
+    releases::{get_current_versions_from_tag, tag_name},
+    state,
+    step::StepError,
+    RunType,
+};
 
 /// Based on the selected issue, either checks out an existing branch matching the name or creates
 /// a new one, prompting for which branch to base it on.

src/issues/github.rs

@@ -1,7 +1,6 @@
-use crate::app_config::get_or_prompt_for_github_token;
-use crate::issues::Issue;
-use crate::step::StepError;
-use crate::{config, state};
+use crate::{
+    app_config::get_or_prompt_for_github_token, config, issues::Issue, state, step::StepError,
+};
 
 const ISSUES_QUERY: &str = r##"
 query($repo: String!, $owner: String!, $labels: [String!]) { 

src/issues/jira.rs

@@ -1,10 +1,12 @@
 use base64::{prelude::BASE64_STANDARD as base64, Engine};
 use serde::{Deserialize, Serialize};
 
-use crate::app_config::{get_or_prompt_for_email, get_or_prompt_for_jira_token};
-use crate::config::Jira;
-use crate::issues::Issue;
-use crate::step::StepError;
+use crate::{
+    app_config::{get_or_prompt_for_email, get_or_prompt_for_jira_token},
+    config::Jira,
+    issues::Issue,
+    step::StepError,
+};
 
 #[derive(Serialize, Debug)]
 struct SearchParams {

src/issues/mod.rs

@@ -1,8 +1,10 @@
 use std::fmt;
 
-use crate::prompt::select;
-use crate::state::{self, RunType, State};
-use crate::step::StepError;
+use crate::{
+    prompt::select,
+    state::{self, RunType, State},
+    step::StepError,
+};
 
 mod github;
 mod jira;

src/lib.rs

@@ -8,11 +8,12 @@ use std::io::stdout;
 
 use clap::Parser;
 use miette::{miette, Result};
-
 use prompt::select;
 
-use crate::config::Config;
-use crate::state::{RunType, State};
+use crate::{
+    config::Config,
+    state::{RunType, State},
+};
 
 mod app_config;
 mod command;

src/main.rs

@@ -4,11 +4,11 @@
 #![allow(clippy::multiple_crate_versions)] // Let cargo-deny handle this
 #![forbid(unsafe_code)]
 
-use clap::Parser;
-use miette::Result;
 use std::env::var;
 
+use clap::Parser;
 use knope::{run, Cli};
+use miette::Result;
 
 fn main() -> Result<()> {
     if var("RUST_LOG").is_ok() {

src/prompt.rs

@@ -1,8 +1,7 @@
 use std::fmt::Display;
 
 use console::Term;
-use dialoguer::theme::ColorfulTheme;
-use dialoguer::{Input, Select};
+use dialoguer::{theme::ColorfulTheme, Input, Select};
 use miette::Result;
 
 use crate::step::StepError;

src/releases/changelog.rs

@@ -1,5 +1,4 @@
-use std::iter::Map;
-use std::slice::Iter;
+use std::{iter::Map, slice::Iter};
 
 use itertools::Itertools;
 

src/releases/conventional_commits.rs

@@ -3,15 +3,21 @@ use std::io::Write;
 use git_conventional::{Commit, Type};
 use log::debug;
 
-use crate::git::{add_files, get_commit_messages_after_last_stable_version};
-use crate::releases::semver::{Label, PackageVersion};
-use crate::releases::Package;
-use crate::step::StepError;
-use crate::{state, step, RunType};
-
-use super::changelog::{add_version_to_changelog, new_changelog_lines};
-use super::semver::{bump_version, ConventionalRule, Rule};
-use super::Release;
+use super::{
+    changelog::{add_version_to_changelog, new_changelog_lines},
+    semver::{bump_version, ConventionalRule, Rule},
+    Release,
+};
+use crate::{
+    git::{add_files, get_commit_messages_after_last_stable_version},
+    releases::{
+        semver::{Label, PackageVersion},
+        Package,
+    },
+    state, step,
+    step::StepError,
+    RunType,
+};
 
 #[derive(Debug)]
 struct ConventionalCommits {

src/releases/git.rs

@@ -1,14 +1,11 @@
-use std::env::current_dir;
-use std::io::Write;
-use std::str::FromStr;
+use std::{env::current_dir, io::Write, str::FromStr};
 
-use git_repository::object::Kind;
-use git_repository::open;
-use git_repository::refs::transaction::PreviousValue;
+use git_repository::{object::Kind, open, refs::transaction::PreviousValue};
 
-use crate::releases::semver::Version;
-use crate::releases::{CurrentVersions, Release};
-use crate::step::StepError;
+use crate::{
+    releases::{semver::Version, CurrentVersions, Release},
+    step::StepError,
+};
 
 pub(crate) fn tag_name(version: &Version, package_name: &Option<String>) -> String {
     let prefix = package_name

src/releases/github.rs

@@ -2,13 +2,14 @@ use std::io::Write;
 
 use serde::Serialize;
 
-use crate::app_config::get_or_prompt_for_github_token;
-use crate::config::GitHub;
-use crate::releases::git::tag_name;
-use crate::releases::Release;
-use crate::state;
-use crate::state::GitHub::{Initialized, New};
-use crate::step::StepError;
+use crate::{
+    app_config::get_or_prompt_for_github_token,
+    config::GitHub,
+    releases::{git::tag_name, Release},
+    state,
+    state::GitHub::{Initialized, New},
+    step::StepError,
+};
 
 pub(crate) fn release(
     release: &Release,

src/releases/go.rs

@@ -1,5 +1,4 @@
-use crate::releases::semver::Version;
-use crate::step::StepError;
+use crate::{releases::semver::Version, step::StepError};
 
 pub(crate) fn set_version(go_mod: String, new_version: &Version) -> Result<String, StepError> {
     let new_major = new_version.stable_component().major;