From 2dbdbc309c5f7e09e7ea4179ea45903c651955b8 Mon Sep 17 00:00:00 2001 From: Nick Gerace Date: Tue, 10 Dec 2024 16:43:53 -0500 Subject: [PATCH] Update documentation to reflect libgfold removal This commit contains documentation changes to reflect libgfold's removal. It also contains the following changes: - Change CHANGELOG process to add changes at release time rather than iteratively (because I never remember to do it nor is it required in pull requests) - Update "Cargo.toml" to have alphabetically sorted fields for two sections - Convert "THANKS" into "COMMUNITY_THANKS" because source code contributors are not included and the document is meant to highlight those who would not normally appear in a GitHub contributors section - Update manual install instructions to new binary names - Remove library section from README This commit also ensures that CI only runs on relevant paths. Signed-off-by: Nick Gerace --- .github/workflows/ci.yml | 8 ++++ CHANGELOG.md | 6 +-- Cargo.toml | 10 ++--- README.md | 30 ++++----------- docs/{THANKS.md => COMMUNITY_THANKS.md} | 4 +- docs/MANUAL_INSTALL.md | 33 +++++++--------- docs/RELEASE.md | 50 ++++--------------------- 7 files changed, 46 insertions(+), 95 deletions(-) rename docs/{THANKS.md => COMMUNITY_THANKS.md} (84%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2712840..0343ccb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,9 +3,17 @@ on: push: branches: - "main" + paths-ignore: + - "**/*.md" + - "LICENSE" + - "assets/*.gif" pull_request: branches: - "main" + paths-ignore: + - "**/*.md" + - "LICENSE" + - "assets/*.gif" concurrency: group: "${{ github.workflow }}-${{ github.ref }}" jobs: diff --git a/CHANGELOG.md b/CHANGELOG.md index 4080b97..37f7963 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,10 @@ # Changelog -- All notable changes to this project will be documented in this file +- All notable, released changes to this project will be documented in this file - All changes are from [@nickgerace](https://github.com/nickgerace) unless otherwise specified - The format was inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) -## Unreleased - -The latest version contains all changes. - ## 4.5.1 - 2024-12-09 ### Changed diff --git a/Cargo.toml b/Cargo.toml index ca9fdb2..cac8d09 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,22 +2,22 @@ name = "gfold" version = "4.5.1" +authors = ["Nick Gerace "] categories = ["command-line-utilities", "command-line-interface"] description = "CLI tool to help keep track of your Git repositories." -keywords = ["git", "cli"] -readme = "README.md" -authors = ["Nick Gerace "] edition = "2021" homepage = "https://github.com/nickgerace/gfold" +keywords = ["git", "cli"] license = "Apache-2.0" +readme = "README.md" repository = "https://github.com/nickgerace/gfold" [profile.release] codegen-units = 1 -opt-level = 3 -strip = true lto = true +opt-level = 3 panic = "abort" +strip = true [dependencies] anyhow = { version = "1.0", features = ["backtrace"] } diff --git a/README.md b/README.md index cc45437..b87cb8b 100644 --- a/README.md +++ b/README.md @@ -112,13 +112,10 @@ Now, you can update the config file within your repository and include the linki [![Packaging status](https://repology.org/badge/vertical-allrepos/gfold.svg)](https://repology.org/project/gfold/versions) -### Homebrew +### Homebrew (macOS and Linux) -You can use [Homebrew](https://brew.sh) to install `gfold` with a choice of two methods. +You can use [Homebrew](https://brew.sh) to install `gfold` using the [core formulae](https://formulae.brew.sh/formula/gfold). -#### Core (macOS and Linux) - -`gfold` is now available in the [core formulae](https://formulae.brew.sh/formula/gfold)! However, you may run into a naming collision on macOS if [coreutils](https://formulae.brew.sh/formula/coreutils) is installed via `brew`. See the [troubleshooting](#troubleshooting-and-known-issues) section for a workaround and more information. @@ -126,15 +123,6 @@ See the [troubleshooting](#troubleshooting-and-known-issues) section for a worka brew install gfold ``` -#### Tap (macOS only) - -The [tap](https://github.com/nickgerace/homebrew-nickgerace/blob/main/Formula/gfold.rb) is still available if you would like to use it. -This is subject to change. - -```shell -brew install nickgerace/nickgerace/gfold -``` - ### Arch Linux You can use [pacman](https://wiki.archlinux.org/title/Pacman) to install `gfold` from the [extra repository](https://archlinux.org/packages/extra/x86_64/gfold/). @@ -187,6 +175,11 @@ For an example on how to do that, refer to the [manual install](./docs/MANUAL_IN If you would like an example on how to build from source, refer to the [manual install](./docs/MANUAL_INSTALL.md) guide. +### Deprecated: Homebrew Tap (macOS only) + +The [tap located at nickgerace/homebrew-nickgerace](https://github.com/nickgerace/homebrew-nickgerace/blob/main/Formula/gfold.rb) has been deprecated. +Please use the aforementioned core Homebrew package instead. + ### Preferred Installation Method Not Listed? Please [file an issue](https://github.com/nickgerace/gfold/issues/new)! @@ -196,13 +189,6 @@ Please [file an issue](https://github.com/nickgerace/gfold/issues/new)! `gfold` is intended to be ran on _any_ tier one Rust 🦀 target. Please [file an issue](https://github.com/nickgerace/gfold/issues) if your platform is unsupported. -## Usage as a Library - -There are two ways to use `gfold` as a "library". - -1. Use the [`libgfold`](./lib/libgfold/README.md) crate that powers `gfold` -1. Consume valid JSON results from `gfold -d json` (not a library, but useful for non-Rust applications) - ## Troubleshooting and Known Issues If you encounter unexpected behavior or a bug and would like to see more details, please run `gfold` with the following @@ -241,7 +227,7 @@ This repository's tracking issue is [#205](https://github.com/nickgerace/gfold/i ## Community -For more information and thanks to contributors, users, and the "community" at large, please refer to the **[THANKS](./docs/THANKS.md)** file. +For more information and thanks to users and the "community" at large, please refer to the **[COMMUNITY THANKS](./docs/COMMUNITY_THANKS.md)** file. - [Packages for NixOS, Arch Linux and more](https://repology.org/project/gfold/versions) - ["One Hundred Rust Binaries"](https://www.wezm.net/v2/posts/2020/100-rust-binaries/page2/), an article that featured `gfold` diff --git a/docs/THANKS.md b/docs/COMMUNITY_THANKS.md similarity index 84% rename from docs/THANKS.md rename to docs/COMMUNITY_THANKS.md index dfd77e1..51330c8 100644 --- a/docs/THANKS.md +++ b/docs/COMMUNITY_THANKS.md @@ -1,4 +1,6 @@ -# Thanks +# Community Thanks + +This document contains "thank you" messages to those who aided or contributed to this project outside of source code changes and issues filed to this repository. - [@AcksID](https://github.com/AckslD/nvim-gfold.lua) for creating and maintaining [nvim-gfold.lua](https://github.com/AckslD/nvim-gfold.lua), a `neovim` plugin for `gfold` - [@jrcichra](https://github.com/jrcichra) for adding multi-OS support to the original, early-stage CI pipeline diff --git a/docs/MANUAL_INSTALL.md b/docs/MANUAL_INSTALL.md index d89a074..1159672 100644 --- a/docs/MANUAL_INSTALL.md +++ b/docs/MANUAL_INSTALL.md @@ -6,8 +6,7 @@ This document contains methods on how to install `gfold` "manually" (i.e. withou Executing the commands in this section requires the following: -- macOS or Linux (GNU, not MUSL) system -- `x86_64 / amd64` architecture +- macOS `aarch64` or Linux (GNU) `x86_64` system - `bash` shell (or compatible) - `jq`, `wget` and `curl` installed and in `PATH` @@ -22,27 +21,23 @@ for BINARY in "jq" "wget" "curl"; do done ``` -Now, let's determine which binary we need to choose based on our platform. +Now, we need to determine to latest tag to build our release URL. ```bash -INSTALL_OS="" -if [ "$(uname -s)" = "Linux" ] && [ "$(uname -m)" = "x86_64" ]; then - INSTALL_OS="linux-gnu" -elif [ "$(uname -s)" = "Darwin" ] && [ "$(uname -m)" = "x86_64" ]; then - INSTALL_OS="darwin" -else - echo "must execute on Linux or Darwin x86_64 (x86_64 / amd64) host" - return -fi +LATEST=$(curl -s https://api.github.com/repos/nickgerace/gfold/releases/latest | jq -r ".tag_name") ``` -We need to determine to latest tag to build our release URL. +Choose our platform. ```bash -LATEST=$(curl -s https://api.github.com/repos/nickgerace/gfold/releases/latest | jq -r ".tag_name") +# If we are using Linux (GNU) x86_64... +INSTALL_PLATFORM=linux-gnu-x84-64 + +# If we are using macOS aarch64 (i.e. Apple Silicon or arm64) +INSTALL_PLATFORM=darwin-aarch64 ``` -With the latest tag and platform determined, we can finally download and install `gfold` to `/usr/local/bin/`. +With the latest tag and platform in hand, we can download and install `gfold` to `/usr/local/bin/`. ```bash # Remove gfold if it is already in /tmp. @@ -51,7 +46,7 @@ if [ -f /tmp/gfold ]; then fi # Perform the download. -wget -O /tmp/gfold https://github.com/nickgerace/gfold/releases/download/$LATEST/gfold-$INSTALL_OS-amd64 +wget -O /tmp/gfold https://github.com/nickgerace/gfold/releases/download/$LATEST/gfold-$INSTALL_PLATFORM # Set executable permissions. chmod +x /tmp/gfold @@ -84,10 +79,8 @@ If you want to install from source locally, and not from [crates.io](https://cra This should work on all major platforms. ```bash -git clone https://github.com/nickgerace/gfold.git -cd gfold; cargo install --path crates/gfold +git clone https://github.com/nickgerace/gfold.git; cd gfold; cargo install ``` The commands above were tested on macOS. -Slight modification may be required for your platform, but the flow should be the same: clone, change directory and run -`cargo install`. \ No newline at end of file +Slight modification may be required for your platform, but the flow should be the same: clone, change directory and run `cargo install`. diff --git a/docs/RELEASE.md b/docs/RELEASE.md index f685c1d..9086b2f 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -10,60 +10,26 @@ Generally, the versioning scheme looks like the following formats where `X` is a - **Release candidates (RCs):** `X.X.X-rc.X` - **Full releases:** `X.X.X` -## Overview - -If only `gfold` has changed, release `gfold` alone. -If `libgfold` has changed, release `libgfold` and _then_ `gfold`. - -## Checklist for `libgfold` - -Steps should be executed in sequential order. - -- [ ] Checkout and rebase `main` to its latest commit and checkout a new branch -- [ ] Change the `version` field in [`Cargo.toml`](../lib/libgfold/Cargo.toml) to the new tag -- [ ] Use the new version in the `gfold` [`Cargo.toml`](../lib/gfold/Cargo.toml) file -- [ ] Change the version in [`CHANGELOG.md`](../CHANGELOG.md) and uncomment the following line: `` (skip this for release candidates) -- [ ] Verify that everything looks/works as expected: - -```shell -just ci -``` - -- [ ] Create and _do not merge_ a commit with the following message: `Update libgfold to ` -- [ ] Test and verify the publishing workflow: - -```shell -cargo publish --dry-run -p libgfold -``` - -- [ ] Merge the preparation commit into `main` -- [ ] Publish the crate: - -```shell -cargo publish -p libgfold -``` - -- [ ] Verify that the [crate](https://crates.io/crates/libgfold) on `crates.io` looks correct -- [ ] Ensure that the [docs](https://docs.rs/libgfold/latest/libgfold/) on `docs.rs` look correct - -## Checklist for `gfold` +## Checklist Steps should be executed in sequential order. - [ ] Checkout and rebase `main` to its latest commit, then checkout a new branch -- [ ] Change the `version` field in [`Cargo.toml`](../bin/gfold/Cargo.toml) to the new tag -- [ ] Change the version in [`CHANGELOG.md`](../CHANGELOG.md) and uncomment the following line: `` (skip this for release candidates) +- [ ] Change the `version` field in [`Cargo.toml`](../Cargo.toml) to the new tag +- [ ] Open a web browser tab to the following link: `https://github.com/nickgerace/gfold/compare/...main` +- [ ] Add a new section the version in [`CHANGELOG.md`](../CHANGELOG.md) with the current date +- [ ] Using the diff, commit messages and commit title, populate the new section with all user-relevant changes - [ ] Verify that everything looks/works as expected: ```shell just ci ``` -- [ ] Create and _do not merge_ a commit with the following message: `Update gfold to ` +- [ ] Create and _do not merge_ a commit with the following message: `Update to ` - [ ] Test and verify the publishing workflow: ```shell -cargo publish --dry-run -p gfold +cargo publish --dry-run ``` - [ ] Merge the preparation commit into `main` @@ -78,7 +44,7 @@ git push --tags origin main - [ ] Publish the crate: ```shell -cargo publish -p gfold +cargo publish ``` - [ ] Verify that the [crate](https://crates.io/crates/gfold) on `crates.io` looks correct