From ddf4a58032a02d91792b2e76903a49fa84c998d3 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 14 Nov 2024 19:17:00 -0500 Subject: [PATCH 1/5] doc: Configure scriv for changelog management --- changelog.d/scriv.ini | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 changelog.d/scriv.ini diff --git a/changelog.d/scriv.ini b/changelog.d/scriv.ini new file mode 100644 index 00000000..1a8cf2d2 --- /dev/null +++ b/changelog.d/scriv.ini @@ -0,0 +1,4 @@ +[scriv] +format = md +main_branches = master, main, dev +version = literal: deno.json: version From d3b672ac90ea85ee6b9532ae760f06a7c7e73a9c Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 14 Nov 2024 19:17:16 -0500 Subject: [PATCH 2/5] doc: Add changelog entry for #113 --- changelog.d/20241114_165444_effigies.md | 42 +++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 changelog.d/20241114_165444_effigies.md diff --git a/changelog.d/20241114_165444_effigies.md b/changelog.d/20241114_165444_effigies.md new file mode 100644 index 00000000..b30ac257 --- /dev/null +++ b/changelog.d/20241114_165444_effigies.md @@ -0,0 +1,42 @@ + + + + + + +### Fixed + +- Improve handling of `.bidsignore` files in the web validator. + Ignores matching directories but not the files they contained could fail to match. + (#113) + + From 868b2d9f9db441599326d6732911c38f95ae9a87 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 14 Nov 2024 19:23:10 -0500 Subject: [PATCH 3/5] doc: Add Infrastructure changelog category --- changelog.d/scriv.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.d/scriv.ini b/changelog.d/scriv.ini index 1a8cf2d2..c344e62c 100644 --- a/changelog.d/scriv.ini +++ b/changelog.d/scriv.ini @@ -2,3 +2,4 @@ format = md main_branches = master, main, dev version = literal: deno.json: version +categories = Added, Changed, Fixed, Deprecated, Removed, Security, Infrastructure From abea32ba8e4caf53a299a5e7c1d709fbcdae0910 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 14 Nov 2024 19:25:10 -0500 Subject: [PATCH 4/5] doc: Add changelog entry for scriv --- changelog.d/20241114_192344_effigies_scriv.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 changelog.d/20241114_192344_effigies_scriv.md diff --git a/changelog.d/20241114_192344_effigies_scriv.md b/changelog.d/20241114_192344_effigies_scriv.md new file mode 100644 index 00000000..b4c968c0 --- /dev/null +++ b/changelog.d/20241114_192344_effigies_scriv.md @@ -0,0 +1,46 @@ + + + + + + + + +### Infrastructure + +- Adopting [scriv](https://scriv.readthedocs.io/en/latest/) for changelog + management. From a2b842dd40c16ebf16bcfd5d4cf027cee80a10e6 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 14 Nov 2024 21:07:29 -0500 Subject: [PATCH 5/5] doc: Update contributing with branch/commit/changelog conventions --- .github/CONTRIBUTING.md | 91 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 8bca6d6f..3873f44f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -161,6 +161,93 @@ git push -u origin feat/short-desc Open PR, set base branch to `dev`. +### Conventions for branches, commits and changelogs + +The following conventions are intended to make contributions legible to other contributors +and, ultimately, users. +They are also there to help you, as a contributor, focus on doing one task at a time. + +The following are common types of contributions, sorted roughly by order of interest +to the reader: + +| Contribution type | Branch prefix | Commit prefix | Changelog section | +|-------------------|---------------|---------------|-------------------------| +| Bug fix | `fix/` | `fix:` | Fixed | +| Feature | `feat/` | `feat:` | Added | +| Documentation | `doc/` | `doc:` | Added or Infrastructure | +| Refactor | `rf/` | `rf:` | Changed | +| Testing | `test/` | `test:` | Changed | +| Style-only | `sty/` | `style:` | Infrastructure | +| Maintenance | `chore/` | `chore:` | Infrastructure | + +If you are contributing a bug-fix, it can help focus your efforts to name your branch +`fix/problem-with-X`, and start commit messages where you write fixes with `fix:`. +Similarly, branches and commits that focus on features, documentation, refactors, +and so on, all have prefixes that help your reader understand what you were trying to do. + +If you find your contribution spanning more than one of these sections, +it might be worth breaking into multiple pull requests. +Exceptions include tests and documentation relevant to the main thrust of the PR, +which are always welcome. + +None of this is set in stone, and we all make mistakes, so don't worry about +following it to the letter. +We will let you know if your contribution is doing too many things and work with +you to split it into more manageable pieces. + +#### Changelog entries + +We are using the [scriv] changelog management tool to help keep our changelog organized. + +Most pull requests will deserve changelog entries, and some may deserve more than one. +Scriv allows changelog entries to be made as part of the pull request, which gives +the contributor and the reviewer a chance to consider the impact of the pull request. + +To add an entry, run: + +``` +scriv create --edit +``` + +(If you're wondering how to install `scriv`, we recommend using [uvx scriv][].) + +Your editor will open a Markdown file with commented sections. +Find the appropriate section(s) for your contribution and write a 1-3 line description. + +#### Style contributions + +Style changes in code can be a source of frustration. +Some editors will reformat entire files when a single line is changed, +swamping the meaningful change with a large number of cosmetic changes. + +We have provided a [`.editorconfig`](https://editorconfig.org) file in the repository, +which should be respected by [most editors](https://editorconfig.org/#pre-installed), +and there are plugins available for [others](https://editorconfig.org/#download). +Additionally, we use `deno fmt` to format the code in this repository. +Using an autoformatter like this helps avoid (ongoing) disagreements over style preferences +so we can focus on the content of the work. + +Even with these, it is possible that when you go to commit your changes, +you have changed more than you intended to. +One reason this can happen is that we might have forgetten to autoformat our code. + +One tool for this situation is `git add --patch` (or `-p`). +This tool shows you each change in turn, allowing you to decide whether or not to +"stage" the change. Stage only the chunks containing the pieces you meant to change, +and commit those. You can then `git checkout .` to discard the remaining changes. + +It is sometimes unavoidable to reformat large portions of code. +In these cases, please make a style-only commit, +followed by a commit with the meaningful changes. +This will speed up review significantly. + +Overall, a style-only pull request should be a rare event, +typically when adopting or upgrading an autoformatter. +This will generally have the effect of introducing merge conflicts, +so we may refrain from doing it for a while. +If you're feeling the urge, it's best to ask! + + [link_git]: https://git-scm.com/ [link_handbook]: https://guides.github.com/introduction/git-handbook/ [link_swc_intro]: http://swcarpentry.github.io/git-novice/ @@ -168,3 +255,7 @@ Open PR, set base branch to `dev`. [link_pullrequest]: https://help.github.com/articles/creating-a-pull-request-from-a-fork [link_fork]: https://help.github.com/articles/fork-a-repo/ [link_clone]: https://help.github.com/articles/cloning-a-repository +[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/ +[git blame]: https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#viewing-the-line-by-line-revision-history-for-a-file +[scriv]: https://scriv.readthedocs.io/en/latest/ +[uvx]: https://docs.astral.sh/uv/guides/tools/