Merge pull request #8 from busticated/feature/changelog

feature/changelog

README.md

@@ -28,14 +28,14 @@ A `cargo` workspace ([docs](https://doc.rust-lang.org/book/ch14-03-cargo-workspa
 
 ## Development
 
-This repository contains a series of `rust` crates managed together as a `cargo` workspace ([docs](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html)) with [XTask](https://github.com/matklad/cargo-xtask). All essential commands are available via `cargo xtask <script name>` - e.g. `cargo xtask todo`. To view the available commands, run: `cargo xtask help`
+This repository contains a series of `rust` crates managed together as a `cargo` workspace ([docs](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html)) with [XTask](https://github.com/matklad/cargo-xtask). All essential commands are available via `cargo xtask <script name>` - e.g. `cargo xtask todo`. To view available commands, run: `cargo xtask help`
 
 
 <details id="develop-add-crate">
 <summary><b>How to add a new crate</b></summary>
 <p>
 
-To add a _new_ crate to the workspace, run `cargo xtask crate:add` and follow the prompts. Upon completion, your new crate will be available within `./crates/<your crate>`
+To add a _new_ crate to the workspace, run `cargo xtask crate:add` and follow the prompts (add the `--dry-run` flag to test). Upon completion, your new crate will be available within `./crates/<your crate>`
 
 </p>
 </details>
@@ -47,34 +47,52 @@ To add a _new_ crate to the workspace, run `cargo xtask crate:add` and follow th
 To run _all_ tests for _all_ crates:
 
 ```
-cargo test
+cargo xtask test
 ```
 
 To run _unit_ tests for _all_ crates:
 
 ```
-cargo test --lib --workspace
+cargo test --lib --all-features --workspace
 ```
 
 To run _unit_ tests for _just your_ crate:
 
 ```
-cargo test --lib --package <your crate's name>
+cargo test --lib --all-features --package <your crate's name>
 ```
 
 To run _integration_ tests for _all_ crates:
 
 ```
-cargo test --test integration --workspace
+cargo test --test integration --all-features --workspace
 ```
 
 To run _integration_ tests for _just your_ crate:
 
 ```
-cargo test --test integration --package <your crate's name>
+cargo test --test integration --all-features --package <your crate's name>
 ```
 
-Run `cargo xtask help` to see any other test-related commands that are available.
+To run tests for _docs_ and _examples_ in _all_ crates:
+
+```
+cargo test --doc --all-features --workspace
+```
+
+To run tests for _docs_ and _examples_ in _just your_ crate:
+
+```
+cargo test --doc --all-features --package <your crate's name>
+```
+
+To run a specific test:
+
+```
+cargo test --all-features <test name - e.g. "tests::it_fetches_node_js_release_info"> -- --exact
+```
+
+To output any `println!()` calls within tests, add the `--nocapture` flag after the `--` option delimiter. Run `cargo xtask help` to see any other test-related commands that are available.
 
 </p>
 </details>
@@ -86,7 +104,7 @@ Run `cargo xtask help` to see any other test-related commands that are available
 To see code coverage stats for _all_ crates:
 
 ```
-cargo xtask coverage
+cargo xtask coverage --open
 ```
 
 Run `cargo xtask help` to see any other coverage-related commands that are available.
@@ -111,14 +129,37 @@ Run `cargo xtask help` to see any other docs-related commands that are available
 </p>
 </details>
 
+<details id="develop-changelog">
+<summary><b>How to format commits for changelogs</b></summary>
+<p>
+
+In order to support automated crate changelog updates, you will need to:
+
+* Commit crate changes separately - e.g. run: `git add -p crates/<name>/*` to stage files, then run `git add -p crates/<other-name>/*` and commit
+* Format your commit message like: `[<crate name>] <message>` e.g. `[node-js-release-info] update docs`
+* Commit changes to the workspace itself (including the `xtask` crate) separately without prefixing your commit message
+
+Each crate has its own changelog ([example](crates/node-js-release-info/CHANGELOG.md)). Upon releasing, each changelog will be updated with the changes made to that crate since its last release.
+
+To view unpublished changelog entries for all crates, run:
+
+```
+cargo xtask changelog
+```
+
+Run `cargo xtask help` to see any other changelog-related commands that are available.
+
+</p>
+</details>
+
 <details id="develop-publish-crate">
 <summary><b>How to publish crates</b></summary>
 <p>
 
 To publish a crate to the [crates.io](https://crates.io) registry, follow these steps:
 
 1. Checkout the `main` branch: `git checkout main`
-2. Run `cargo xtask crate:release` and follow the prompts
+2. Run `cargo xtask crate:release` and follow the prompts (add the `--dry-run` flag to test)
 3. Verify all checks pass: `cargo xtask ci`
 4. Push to remote: `git push origin main --follow-tags`
 
@@ -149,6 +190,8 @@ e.g.
 // TODO (busticated): this is my example todo comment
 ```
 
+Any `todo!()` macros in the source code will also be reported.
+
 </p>
 </details>
 
@@ -162,5 +205,6 @@ e.g.
 * [Duct](https://github.com/oconnor663/duct.rs)
 * [TOML](https://github.com/toml-rs/toml)
 * [Inquire](https://github.com/mikaelmello/inquire)
+* [Reqwest](https://github.com/seanmonstar/reqwest)
 * [Mockito](https://github.com/lipanski/mockito)
 

crates/detect-newline-style/CHANGELOG.md

@@ -1,5 +1,6 @@
 # `detect-newline-style` Changelog
-
+<!-- next-version-start -->
+<!-- next-version-end -->
 ## v0.1.1
 
 * add tests to cover no-op cases

crates/node-js-release-info/CHANGELOG.md

@@ -1,6 +1,6 @@
 # `node-js-release-info` Changelog
-
-
+<!-- next-version-start -->
+<!-- next-version-end -->
 ## v1.1.0
 
 * add docs and examples for .fetch_all() method

crates/node-js-release-info/src/error.rs

@@ -45,9 +45,7 @@ impl Display for NodeJSRelInfoError {
             NodeJSRelInfoError::UnrecognizedConfiguration(input) => {
                 format!("Unrecognized Configuration! Received: '{}'", input)
             }
-            NodeJSRelInfoError::HttpError(e) => {
-                return write!(f, "{}", e)
-            }
+            NodeJSRelInfoError::HttpError(e) => return write!(f, "{}", e),
         };
 
         write!(f, "Error: {}", message)

crates/node-js-release-info/src/lib.rs

@@ -1,20 +1,20 @@
 #![doc = include_str!("../README.md")]
 
-mod os;
 mod arch;
 mod error;
 mod ext;
+mod os;
 mod specs;
 mod url;
 
-use std::string::ToString;
-#[cfg(feature = "json")]
-use serde::{Serialize, Deserialize};
-pub use crate::os::NodeJSOS;
 pub use crate::arch::NodeJSArch;
 pub use crate::error::NodeJSRelInfoError;
 pub use crate::ext::NodeJSPkgExt;
+pub use crate::os::NodeJSOS;
 use crate::url::NodeJSURLFormatter;
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+use std::string::ToString;
 
 #[derive(Clone, Debug, Default, PartialEq)]
 #[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
@@ -322,9 +322,7 @@ impl NodeJSRelInfo {
         let version = specs::validate_version(self.version.as_str())?;
         let specs = specs::fetch(&version, &self.url_fmt).await?;
         let filename = self.filename();
-        let info = specs.lines().find(|&line| {
-            line.contains(filename.as_str())
-        });
+        let info = specs.lines().find(|&line| line.contains(filename.as_str()));
 
         let mut specs = match info {
             None => return Err(NodeJSRelInfoError::UnrecognizedConfiguration(filename))?,
@@ -403,13 +401,13 @@ impl NodeJSRelInfo {
 
 #[cfg(test)]
 mod tests {
-    use mockito::Server;
     use super::*;
+    use mockito::Server;
 
     fn is_thread_safe<T: Sized + Send + Sync + Unpin>() {}
 
     #[test]
-    fn it_initializes(){
+    fn it_initializes() {
         let info = NodeJSRelInfo::new("1.0.0");
         assert_eq!(info.os, NodeJSOS::Linux);
         assert_eq!(info.arch, NodeJSArch::X64);
@@ -563,7 +561,8 @@ mod tests {
         let version = "20.6.1".to_string();
         let filename = "node-v20.6.1-darwin-arm64.tar.gz".to_string();
         let sha256 = "d8ba8018d45b294429b1a7646ccbeaeb2af3cdf45b5c91dabbd93e2a2035cb46".to_string();
-        let url = "https://nodejs.org/download/release/v20.6.1/node-v20.6.1-darwin-arm64.tar.gz".to_string();
+        let url = "https://nodejs.org/download/release/v20.6.1/node-v20.6.1-darwin-arm64.tar.gz"
+            .to_string();
         let info_orig = NodeJSRelInfo {
             os: NodeJSOS::Darwin,
             arch: NodeJSArch::ARM64,
@@ -580,20 +579,34 @@ mod tests {
         assert_eq!(info.arch, NodeJSArch::ARM64);
         assert_eq!(info.ext, NodeJSPkgExt::Targz);
         assert_eq!(info.version, "20.6.1".to_string());
-        assert_eq!(info.filename, "node-v20.6.1-darwin-arm64.tar.gz".to_string());
-        assert_eq!(info.sha256, "d8ba8018d45b294429b1a7646ccbeaeb2af3cdf45b5c91dabbd93e2a2035cb46".to_string());
-        assert_eq!(info.url, "https://nodejs.org/download/release/v20.6.1/node-v20.6.1-darwin-arm64.tar.gz".to_string());
+        assert_eq!(
+            info.filename,
+            "node-v20.6.1-darwin-arm64.tar.gz".to_string()
+        );
+        assert_eq!(
+            info.sha256,
+            "d8ba8018d45b294429b1a7646ccbeaeb2af3cdf45b5c91dabbd93e2a2035cb46".to_string()
+        );
+        assert_eq!(
+            info.url,
+            "https://nodejs.org/download/release/v20.6.1/node-v20.6.1-darwin-arm64.tar.gz"
+                .to_string()
+        );
     }
 
     #[tokio::test]
-    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: InvalidVersion(\"NOPE!\")")]
+    #[should_panic(
+        expected = "called `Result::unwrap()` on an `Err` value: InvalidVersion(\"NOPE!\")"
+    )]
     async fn it_fails_to_fetch_info_when_version_is_invalid() {
         let mut info = NodeJSRelInfo::new("NOPE!");
         info.fetch().await.unwrap();
     }
 
     #[tokio::test]
-    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: UnrecognizedVersion(\"1.0.0\")")]
+    #[should_panic(
+        expected = "called `Result::unwrap()` on an `Err` value: UnrecognizedVersion(\"1.0.0\")"
+    )]
     async fn it_fails_to_fetch_info_when_version_is_unrecognized() {
         let mut info = NodeJSRelInfo::new("1.0.0");
         let mut server = Server::new_async().await;
@@ -608,7 +621,9 @@ mod tests {
     }
 
     #[tokio::test]
-    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: UnrecognizedConfiguration(\"node-v20.6.1-linux-x64.zip\")")]
+    #[should_panic(
+        expected = "called `Result::unwrap()` on an `Err` value: UnrecognizedConfiguration(\"node-v20.6.1-linux-x64.zip\")"
+    )]
     async fn it_fails_to_fetch_info_when_configuration_is_unrecognized() {
         let mut server = Server::new_async().await;
         let mut info = NodeJSRelInfo::new("20.6.1").linux().zip().to_owned();
@@ -634,8 +649,18 @@ mod tests {
         mock.assert_async().await;
 
         assert_eq!(info.filename, "node-v20.6.1-linux-x64.tar.gz");
-        assert_eq!(info.url, format!("{}{}", server.url(), "/download/release/v20.6.1/node-v20.6.1-linux-x64.tar.gz"));
-        assert_eq!(info.sha256, "26dd13a6f7253f0ab9bcab561353985a297d927840771d905566735b792868da");
+        assert_eq!(
+            info.url,
+            format!(
+                "{}{}",
+                server.url(),
+                "/download/release/v20.6.1/node-v20.6.1-linux-x64.tar.gz"
+            )
+        );
+        assert_eq!(
+            info.sha256,
+            "26dd13a6f7253f0ab9bcab561353985a297d927840771d905566735b792868da"
+        );
     }
 
     #[tokio::test]
@@ -651,8 +676,18 @@ mod tests {
         mock.assert_async().await;
 
         assert_eq!(info.filename, "node-v20.6.1-arm64.msi");
-        assert_eq!(info.url, format!("{}{}", server.url(), "/download/release/v20.6.1/node-v20.6.1-arm64.msi"));
-        assert_eq!(info.sha256, "9471bd6dc491e09c31b0f831f5953284b8a6842ed4ccb98f5c62d13e6086c471");
+        assert_eq!(
+            info.url,
+            format!(
+                "{}{}",
+                server.url(),
+                "/download/release/v20.6.1/node-v20.6.1-arm64.msi"
+            )
+        );
+        assert_eq!(
+            info.sha256,
+            "9471bd6dc491e09c31b0f831f5953284b8a6842ed4ccb98f5c62d13e6086c471"
+        );
     }
 
     #[tokio::test]
@@ -673,12 +708,20 @@ mod tests {
         assert_eq!(all[2].arch, NodeJSArch::ARM64);
         assert_eq!(all[2].ext, NodeJSPkgExt::Targz);
         assert_eq!(all[2].filename, "node-v20.6.1-darwin-arm64.tar.gz");
-        assert_eq!(all[2].sha256, "d8ba8018d45b294429b1a7646ccbeaeb2af3cdf45b5c91dabbd93e2a2035cb46");
-        assert_eq!(all[2].url, "https://nodejs.org/download/release/v20.6.1/node-v20.6.1-darwin-arm64.tar.gz");
+        assert_eq!(
+            all[2].sha256,
+            "d8ba8018d45b294429b1a7646ccbeaeb2af3cdf45b5c91dabbd93e2a2035cb46"
+        );
+        assert_eq!(
+            all[2].url,
+            "https://nodejs.org/download/release/v20.6.1/node-v20.6.1-darwin-arm64.tar.gz"
+        );
     }
 
     #[tokio::test]
-    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: UnrecognizedVersion(\"1.0.0\")")]
+    #[should_panic(
+        expected = "called `Result::unwrap()` on an `Err` value: UnrecognizedVersion(\"1.0.0\")"
+    )]
     async fn it_fails_to_fetch_all_supported_node_js_configurations_when_version_is_unrecognized() {
         let mut info = NodeJSRelInfo::new("1.0.0");
         let mut server = Server::new_async().await;