From 5d915af469fb614736a725e89e2412992e023d68 Mon Sep 17 00:00:00 2001 From: Andrea C <3269984+andreacfromtheapp@users.noreply.github.com> Date: Sun, 20 Oct 2024 11:34:59 +0200 Subject: [PATCH] chore: Onemoretryatorgreadme (#69) --- .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- .../pull_request_template.md | 2 - .github/workflows/ci.yml | 36 ++--- Cargo.toml | 6 +- README.md | 118 ---------------- README.org | 133 ++++++++++++++++++ docs/CONTRIBUTING.org | 24 ---- docs/RATIONALE.org | 7 +- spellcheck.dic | 3 +- 9 files changed, 160 insertions(+), 171 deletions(-) delete mode 100644 README.md create mode 100644 README.org diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index b3f0117..a28f26b 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -8,7 +8,7 @@ body: label: Did you check the docs? description: Make sure you read all the docs before submitting a feature request options: - - label: I have read all the freesound-credits README.md + - label: I have read all the freesound-credits README required: true - type: textarea diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 67e7f65..cea0f1d 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -17,8 +17,6 @@ Team member before any CI builds will run. - [ ] Read the [Code Of Conduct](/CODE_OF_CONDUCT.md) (required) - [ ] Include tests for your changes (if necessary) - [ ] `pre-commit run --all-files` returns no issues (required) -- [ ] Spell-check with `cargo spellcheck check` (required) -- [ ] Update the `spellcheck.dic` (if necessary) - [ ] Update any related documentation and include any relevant screenshots - [ ] Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (required) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 489cf7e..8790afc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -108,21 +108,21 @@ jobs: - name: cargo docs run: cargo doc --no-deps --document-private-items --all-features --workspace --examples - check-spelling: - name: check-spelling - needs: basics - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - name: Install Rust ${{ env.rust_stable }} - uses: dtolnay/rust-toolchain@stable - with: - toolchain: ${{ env.rust_stable }} - - name: Install cargo-spellcheck - uses: taiki-e/install-action@v2 - with: - tool: cargo-spellcheck - - uses: actions/checkout@v4 - - name: cargo spellcheck - run: cargo spellcheck --code 1 + # check-spelling: + # name: check-spelling + # needs: basics + # runs-on: ubuntu-latest + # steps: + # - name: Checkout repository + # uses: actions/checkout@v4 + # - name: Install Rust ${{ env.rust_stable }} + # uses: dtolnay/rust-toolchain@stable + # with: + # toolchain: ${{ env.rust_stable }} + # - name: Install cargo-spellcheck + # uses: taiki-e/install-action@v2 + # with: + # tool: cargo-spellcheck + # - uses: actions/checkout@v4 + # - name: cargo spellcheck + # run: cargo spellcheck --code 1 diff --git a/Cargo.toml b/Cargo.toml index 8002168..ba1619c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,7 @@ authors = ["Andrea C From The App"] homepage = "https://andreacfromtheapp.github.io/apps/freesound-credits" repository = "https://github.com/andreacfromtheapp/freesound-credits" description = "A simple command line utility to credit Freesound samples in a usable markdown file" -readme = "README.md" +readme = "README.org" keywords = ["freesound", "creative-commons", "credits"] categories = ["command-line-utilities"] @@ -36,8 +36,8 @@ pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }.{ archive bin-dir = "{ bin }{ binary-ext }" pkg-fmt = "zip" -[package.metadata.spellcheck] -config = "spellcheck.toml" +# [package.metadata.spellcheck] +# config = "spellcheck.toml" [workspace.metadata.dist] # The preferred cargo-dist version to use in CI (Cargo.toml SemVer syntax) diff --git a/README.md b/README.md deleted file mode 100644 index 6d4571f..0000000 --- a/README.md +++ /dev/null @@ -1,118 +0,0 @@ -# freesound-credits - -A command line utility to help you credit [Freesound](https://freesound.org) -samples for a given project more easily. - -[![Commitlint](https://github.com/gacallea/freesound-credits/actions/workflows/commitlint.yml/badge.svg)](https://github.com/gacallea/freesound-credits/actions/workflows/commitlint.yml) -[![Trufflehog](https://github.com/gacallea/freesound-credits/actions/workflows/trufflehog.yml/badge.svg)](https://github.com/gacallea/freesound-credits/actions/workflows/trufflehog.yml) -[![CI](https://github.com/gacallea/freesound-credits/actions/workflows/ci.yml/badge.svg)](https://github.com/gacallea/freesound-credits/actions/workflows/ci.yml) -[![CD](https://github.com/gacallea/freesound-credits/actions/workflows/release-plz.yml/badge.svg)](https://github.com/gacallea/freesound-credits/actions/workflows/release-plz.yml) -[![Release](https://github.com/gacallea/freesound-credits/actions/workflows/release.yml/badge.svg)](https://github.com/gacallea/freesound-credits/actions/workflows/release.yml) -[![Crates.io](https://img.shields.io/crates/v/freesound%2Dcredits.svg)](https://crates.io/crates/freesound-credits) -[![License: -Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -[![License: -MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) - -## Giving credits - -Giving credits in the [Creative Commons](https://creativecommons.org) community -is often the sole requirement to freely use samples in your own creations. This -tool helps you abide to [Copyleft](https://en.wikipedia.org/wiki/Copyleft) -and credit the generous artists that contribute sounds on -[Freesound](https://freesound.org), helping you being more creative. - -Until today, giving credits may have been a process that you begrudged. This -may have been stopping you from giving credits altogether. Not because you -didn't want to, but because it was cumbersome and tedious. - -Not anymore! Thanks to `freesound-credits` it takes seconds now! - -## Install - -Use [`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) to install -`freesound-credits` directly from GitHub: - -```shell -cargo binstall freesound-credits -``` - -### Homebrew - -On Linux and macOS homebrew is also available: - -```shell -brew install gacallea/tap/freesound-credits -``` - -## Usage - -The command line comes with a straight-forward usage function: - -```bash -freesound-credits -h -``` - -### Usage example - -1. open your favorite terminal. -2. `cd` to the folder where you want to save the credits file. -3. run `freesound-credits` on your desired samples folder. -4. if necessary, use the absolute path to the samples folder. - -#### Ableton Example - -Running against an Ableton `Samples/Imported` directory, will generate a -markdown file named `field-notes-credits.md` in the current directory. - -```bash -freesound-credits -p Samples/Imported/ -t "Field Notes" -a "Aner Andros" -d "2017-10-28" -``` - -## Supported file names - -`freesound-credits` matches samples adhering to Freesound naming standard that -kept their original samples names per downloads from the platform. For example: - -- new standard with double underscore: `69604__timkahn__subverse_whisper.wav` -- old standard with single underscore: `2166_suburban_grilla_bowl_struck.flac` - -## Supported DAWs - -`freesound-credits` should work for any samples stored in a flat folder. -`freesound-credits` filters out metadata files associated with audio imports. -To add more DAWs and associated metadata or extraction, please [file an -issue](https://github.com/gacallea/freesound-credits/issues/new?assignees=&labels=enhancement&projects=&template=add_a_new_daw.yml&title=feat%28DAW%29%3A+add+). - -| DAW | Samples Folder | Metadata | Extraction | Notes | -| :----: | :----: | :----: | :----: | :----: | -| Ableton | `Samples/Imported` | `.asd` | no | | -| Reaper | `Audio Files` | `.reapeaks` | no | | -| Renoise | `SamplesData` | no | `unzip` | [extraction](#renoise-extraction) | -| Logic Pro X | `Audio Files` | no | no | [Package vs Folder](https://www.youtube.com/watch?v=33zVydB4MiI) | - -### Adding more DAWs - -I did the best I could with what I have. I've tested it with Ableton, Reaper, -and Renoise projects on macOS. Logic Pro X uses no metadata and a clean Audio -files folder, thus I decided to add it but it hasn't been tested. - -However, any DAW with these characteristics should work out of the box. I would -appreciate anybody confirming more DAWs or [adding new -ones](https://github.com/gacallea/freesound-credits/issues/new?assignees=&labels=enhancement&projects=&template=add_a_new_daw.yml&title=feat%28DAW%29%3A+add+). -When you do request or add a new DAW, please keep the [above -table](#supported-daws) and the [extra steps](#extra-daws-steps) section in -mind for any extra information. - -## Extra DAWs steps - -### Renoise extraction - -Extract with `unzip your_project.xrns` first. Once unzipped, you will find a -`Song.xml` file and a `SamplesData` directory containing each `Instrument`. - -## Contributing - -Thanks for your help improving the project! :balloon: Happy to have you! Peruse -the [contributing guide](./docs/CONTRIBUTING.org) to help you get involved in -the project. diff --git a/README.org b/README.org new file mode 100644 index 0000000..cf171d7 --- /dev/null +++ b/README.org @@ -0,0 +1,133 @@ +* freesound-credits +:PROPERTIES: +:CUSTOM_ID: freesound-credits +:END: +A command line utility to help you credit [[https://freesound.org][Freesound]] samples for a given project +more easily. + +[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/commitlint.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/commitlint.yml/badge.svg]] +[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/ci.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/ci.yml/badge.svg]] +[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/trufflehog.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/trufflehog.yml/badge.svg]] +[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release-plz.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release-plz.yml/badge.svg]] +[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release.yml/badge.svg]] +[[https://crates.io/crates/freesound-credits][https://img.shields.io/crates/v/freesound%2Dcredits.svg]] +[[https://opensource.org/licenses/Apache-2.0][https://img.shields.io/badge/License-Apache_2.0-blue.svg]] + +** Giving credits +:PROPERTIES: +:CUSTOM_ID: giving-credits +:END: +Giving credits in the [[https://creativecommons.org][Creative Commons]] community is often the sole requirement +to freely use samples in your own creations. This tool helps you abide to +[[https://en.wikipedia.org/wiki/Copyleft][Copyleft]] and credit the generous artists who contribute to [[https://freesound.org][Freesound]], and help +you being more creative. + +Until today, giving credits may have been a process that you begrudged. This may +have been stopping you from giving credits altogether. Not because you didn't +want to, but because it was cumbersome and tedious. + +Not anymore! Thanks to =freesound-credits= it takes seconds now! + +** Install +:PROPERTIES: +:CUSTOM_ID: install +:END: +Use [[https://github.com/cargo-bins/cargo-binstall][=cargo binstall=]] to install =freesound-credits= directly from GitHub: + +#+begin_src shell +cargo binstall freesound-credits +#+end_src + +*** Homebrew +:PROPERTIES: +:CUSTOM_ID: homebrew +:END: +On Linux and macOS homebrew is also available: + +#+begin_src shell +brew install andreacfromtheapp/tap/freesound-credits +#+end_src + +** Usage +:PROPERTIES: +:CUSTOM_ID: usage +:END: +The command line comes with a straight-forward usage function: + +#+begin_src sh +freesound-credits -h +#+end_src + +*** Usage example +:PROPERTIES: +:CUSTOM_ID: usage-example +:END: +1. open your favorite terminal. +2. =cd= to the folder where you want to save the credits file. +3. run =freesound-credits= on your desired samples folder. +4. if necessary, use the absolute path to the samples folder. + +**** Ableton Example + +Running against an Ableton =Samples/Imported= directory, will generate a +markdown file named =field-notes-credits.md= in the current directory. + +#+begin_src sh + freesound-credits -p Samples/Imported/ -t "Field Notes" -a "Aner Andros" -d "2017-10-28" +#+end_src + +** Supported file names +:PROPERTIES: +:CUSTOM_ID: supported-file-names +:END: +=freesound-credits= matches samples adhering to Freesound naming standard that +kept their original samples names per downloads from the platform. For example: + +- new standard with double underscore: =69604__timkahn__subverse_whisper.wav= +- old standard with single underscore: =2166_suburban_grilla_bowl_struck.flac= + +** Supported DAWs +:PROPERTIES: +:CUSTOM_ID: supported-daws +:END: +=freesound-credits= should work for any samples stored in a flat folder. +=freesound-credits= filters out metadata files associated with audio imports. To +add more DAWs and associated metadata or extraction, please [[https://github.com/gacallea/freesound-credits/issues/new?assignees=&labels=enhancement&projects=&template=add_a_new_daw.yml&title=feat%28DAW%29%3A+add+][file an issue]]. + +| DAW | Samples Folder | Metadata | Extraction | Notes | +|-------------+--------------------+-------------+------------+-------------------| +| Ableton | =Samples/Imported= | =.asd= | no | | +| Reaper | =Audio Files= | =.reapeaks= | no | | +| Renoise | =SamplesData= | no | =unzip= | [[#renoise-extraction][extraction]] | +| Logic Pro X | =Audio Files= | no | no | [[https://www.youtube.com/watch?v=33zVydB4MiI][Package vs Folder]] | + +*** Adding more DAWs +:PROPERTIES: +:CUSTOM_ID: adding-more-daws +:END: +I did the best I could with what I have. I've tested it with Ableton, Reaper, +and Renoise projects on macOS. Logic Pro X uses no metadata and a clean Audio +files folder, thus I decided to add it but it hasn't been tested. + +However, any DAW with these characteristics should work out of the box. I would +appreciate anybody confirming more DAWs or [[https://github.com/gacallea/freesound-credits/issues/new?assignees=&labels=enhancement&projects=&template=add_a_new_daw.yml&title=feat%28DAW%29%3A+add+][adding new ones]]. When you do request +or add a new DAW, please keep the [[#supported-daws][above table]] and the [[#extra-daws-steps][extra steps]] section in +mind for any extra information. + +** Extra DAWs steps +:PROPERTIES: +:CUSTOM_ID: extra-daws-steps +:END: +*** Renoise extraction +:PROPERTIES: +:CUSTOM_ID: renoise-extraction +:END: +Extract with =unzip your_project.xrns= first. Once unzipped, you will find a +=Song.xml= file and a =SamplesData= directory containing each =Instrument=. + +** Contributing +:PROPERTIES: +:CUSTOM_ID: contributing +:END: +Thanks for your help improving the project! :balloon: Happy to have you! Peruse +the [[./docs/CONTRIBUTING.md][contributing guide]] to help you get involved in the project. diff --git a/docs/CONTRIBUTING.org b/docs/CONTRIBUTING.org index b39caee..ff6c95a 100644 --- a/docs/CONTRIBUTING.org +++ b/docs/CONTRIBUTING.org @@ -135,7 +135,6 @@ guaranteeing contracts before committing any changes. - Install [[https://github.com/rust-secure-code/cargo-auditable][=cargo auditable=]]: =cargo install cargo-auditable --locked= - Set up a [[https://github.com/rust-secure-code/cargo-auditable?tab=readme-ov-file#can-i-make-cargo-always-build-with-cargo-auditable][shell alias for =cargo auditable=]] - Install [[https://embarkstudios.github.io/cargo-deny/][=cargo deny=]]: =cargo install cargo-deny --locked= -- Install [[https://github.com/drahnr/cargo-spellcheck][=cargo-spellcheck=]]: =cargo install cargo-spellcheck --locked= - Install [[https://trufflesecurity.com/trufflehog][=trufflehog=]]: =brew install trufflehog= - Otherwise, download a binary from [[https://github.com/trufflesecurity/trufflehog/releases][=trufflehog= release page]]. - Install [[https://pre-commit.com][=pre-commit=]]: =pip install pre-commit= @@ -201,29 +200,6 @@ pre-commit run --all-files *Should it present any warning or issue: please fix, rinse, and repeat.* -*** Performing spell-check on the codebase -:PROPERTIES: -:CUSTOM_ID: performing-spell-check-on-the-codebase -:END: -To perform spell-check on the codebase, run: - -#+begin_src shell -cargo spellcheck checkout -#+end_src - -For details of how to use the spellcheck tool, visit [[https://github.com/drahnr/cargo-spellcheck][cargo-spellcheck -repository]]. - -Should the command decline a word, you should backtick the declined word if code -related. If not, the rejected word should go into =spellcheck.dic= file. - -#+begin_quote -[!IMPORTANT] -When you add a word into the file, you should also update -the first line which tells the spellcheck tool the total number of words -included in the file -#+end_quote - *** Testing :PROPERTIES: :CUSTOM_ID: testing diff --git a/docs/RATIONALE.org b/docs/RATIONALE.org index 9131306..231b0f2 100644 --- a/docs/RATIONALE.org +++ b/docs/RATIONALE.org @@ -101,10 +101,9 @@ legacy and stagnation, as =AppSec= best practices dictate. :END: Besides standardized [[https://www.rust-lang.org/tools][tooling]] and [[https://doc.rust-lang.org/beta/style-guide/index.html][conventions]], default =rustfmt= and =clippy=, this project relies on [[https://rustsec.org][RustSec]] to inspect supply chain, and [[https://trufflesecurity.com][=trufflehog=]] to -avoid sharing secrets in the code base. To fix [[https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments][the crate documentation comments]] -and avoid typos in the source tree, this project relies on =cargo-spellcheck=. -Likewise, this project relies on [[https://github.com/DavidAnson/markdownlint-cli2][=markdownlint-cli2=]] and [[https://github.com/pre-commit/pre-commit-hooks][=pre-commit-hooks=]]. All -conveniently enforced with [[https://githooks.com][Git Hooks]]. +avoid sharing secrets in the code base. Likewise, this project relies on +[[https://github.com/DavidAnson/markdownlint-cli2][=markdownlint-cli2=]] and [[https://github.com/pre-commit/pre-commit-hooks][=pre-commit-hooks=]]. All conveniently enforced with [[https://githooks.com][Git +Hooks]]. ** Fully Automated Releases :PROPERTIES: diff --git a/spellcheck.dic b/spellcheck.dic index c68f01d..58fee9e 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -1,4 +1,4 @@ -26 +27 & + < @@ -23,3 +23,4 @@ trufflehog homebrew io metadata +md