From 0be55dbd26d21f58e0abaacb8b0f114af4403486 Mon Sep 17 00:00:00 2001 From: Dane Hillard Date: Fri, 16 Feb 2024 07:11:42 -0500 Subject: [PATCH] Update flavors to types (#27) --- README.md | 2 +- docs/CHANGELOG.md | 1 + .../0006-change-flavor-terminology-to-type.md | 22 +++++++ docs/index.rst | 58 +++++++++---------- setup.cfg | 2 +- src/repo_man/cli.py | 4 +- .../commands/{flavors.py => types.py} | 2 +- test/{test_flavors.py => test_types.py} | 18 +++--- 8 files changed, 66 insertions(+), 43 deletions(-) create mode 100644 docs/architecture/decisions/0006-change-flavor-terminology-to-type.md rename src/repo_man/commands/{flavors.py => types.py} (89%) rename test/{test_flavors.py => test_types.py} (75%) diff --git a/README.md b/README.md index 3db7c2c..84bc155 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # repo-man -Manage repositories of different flavors. +Manage repositories of a variety of different types. Read [the full documentation](https://repo-man.readthedocs.org) to learn more. ## Installation diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 8a3f2e6..f990d80 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Update `flavors` command and terminology to `types` - Use `strict` for mypy type checking on source and tests - Add isort to order imports consistently diff --git a/docs/architecture/decisions/0006-change-flavor-terminology-to-type.md b/docs/architecture/decisions/0006-change-flavor-terminology-to-type.md new file mode 100644 index 0000000..15980f0 --- /dev/null +++ b/docs/architecture/decisions/0006-change-flavor-terminology-to-type.md @@ -0,0 +1,22 @@ +# 6. Change flavor terminology to type + +Date: 2024-02-15 + +## Status + +Accepted + +## Context + +The "flavor" terminology is a bit too playful and perhaps unfamiliar to people of some backgrounds. +The word "type," while possibly a bit generic, is more aligned with colloquial discussion about repositories. + +## Decision + +Change the word "flavor" to "type" wherever applicable. + +## Consequences + +- People might better understand what this tool does +- Documentation needs to be updated to reflect the new terminology +- Commands like `flavors` need to change, and will break usage as a result diff --git a/docs/index.rst b/docs/index.rst index 92da912..ee34482 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ Welcome to repo-man's documentation! ==================================== -Manage repositories of different flavors. +Manage repositories of different types. .. toctree:: :maxdepth: 2 @@ -20,14 +20,14 @@ Manage repositories of different flavors. If you work in open source or as a cross-team individual contributor in your organization, you may have dozens of repositories cloned to your local machine. -Those repositories may be of several different *flavors*, exhibiting a particular file structure or purpose. +Those repositories may be of several different *types*, exhibiting a particular file structure or purpose. -You may find yourself wanting to query or mutate repositories of a particular flavor and, -unless the repositories of that flavor share a common name prefix or some other signifier, +You may find yourself wanting to query or mutate repositories of a particular type and, +unless the repositories of that type share a common name prefix or some other signifier, it can prove tedious to specify which repositories to run commands against. Even great tools like `fzf `_ don't quite reduce the burden of selecting all desired repositories at this scale. -repo-man is a tool for managing a catalog of repositories and their flavors to improve your productivity. +repo-man is a tool for managing a catalog of repositories and their types to improve your productivity. Getting started --------------- @@ -49,19 +49,19 @@ Configuration ************* To configure repo-man, create a :file:`repo-man.cfg` file alongside your cloned repositories. -This file is an INI-style file with sections, where each section name is a repository flavor. -In each repository flavor section, a single ``known`` property specifies a newline-delimited list of repositories. +This file is an INI-style file with sections, where each section name is a repository type. +In each repository type section, a single ``known`` property specifies a newline-delimited list of repositories. A valid :file:`repo-man.cfg` file might look something like the following: .. code-block:: cfg - [some-flavor] + [some-type] known = repo-one repo-two - [some-other-flavor] + [some-other-type] known = repo-three @@ -98,52 +98,52 @@ Listing repositories .. code-block:: shell - $ repo-man list --type some-flavor + $ repo-man list --type some-type repo-one repo-two -Listing flavors for a repository +Listing types for a repository ++++++++++++++++++++++++++++++++ .. code-block:: shell - $ repo-man flavors repo-one - some-flavor + $ repo-man types repo-one + some-type Adding a repository +++++++++++++++++++ -You can add a repository to an existing flavor: +You can add a repository to an existing type: .. code-block:: shell - $ repo-man add repo-four --type some-flavor + $ repo-man add repo-four --type some-type -You can also add a repository to an existing flavor: +You can also add a repository to an existing type: .. code-block:: shell - $ repo-man add repo-five --type some-brand-new-flavor + $ repo-man add repo-five --type some-brand-new-type -Listing known flavors +Listing known types +++++++++++++++++++++ .. code-block:: shell $ repo-man sniff --known - some-flavor - some-other-flavor + some-type + some-other-type Combining with other tools ++++++++++++++++++++++++++ The value of repo-man comes in when combining its output with other tools. -As an example, you can iterate over all the repositories of a given flavor to take some action: +As an example, you can iterate over all the repositories of a given type to take some action: .. code-block:: shell - $ for repo in $(repo-man list --type some-flavor); do + $ for repo in $(repo-man list --type some-type); do cd $repo; # take some action; cd ..; @@ -158,7 +158,7 @@ These commands help you query and improve your repo-man configuration. Unconfigured repositories ^^^^^^^^^^^^^^^^^^^^^^^^^ -List repositories you have cloned but that have no configured flavor: +List repositories you have cloned but that have no configured type: .. code-block:: shell @@ -169,17 +169,17 @@ List repositories you have cloned but that have no configured flavor: Duplicate repositories ^^^^^^^^^^^^^^^^^^^^^^ -Some repositories may be of multiple flavors, but you may also accidentally configure a repository as two flavors. -You can list all the repositories that you've configured as more than one flavor: +Some repositories may be of multiple types, but you may also accidentally configure a repository as two types. +You can list all the repositories that you've configured as more than one type: .. code-block:: cfg - [some-flavor] + [some-type] known = repo-one repo-two - [some-other-flavor] + [some-other-type] known = repo-one @@ -192,7 +192,7 @@ You can list all the repositories that you've configured as more than one flavor Tips and tricks +++++++++++++++ -You may wish to create a hierarchy of flavors, starting your flavor names with the most general classification. +You may wish to create a hierarchy of types, starting your type names with the most general classification. As an example, you may have several different package and application types that you could capture as follows: .. code-block:: cfg @@ -215,7 +215,7 @@ As an example, you may have several different package and application types that left-pad is-even -repo-man doesn't currently do anything special with these, but could grow features to e.g. list flavor classes. +repo-man doesn't currently do anything special with these, but could grow features to e.g. list type classes. Indices and tables ================== diff --git a/setup.cfg b/setup.cfg index 89912ef..79458ec 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,7 +1,7 @@ [metadata] name = repo-man version = 0.0.8 -description = Manage repositories of different flavors. +description = Manage repositories of a variety of different types. long_description = file: README.md long_description_content_type = text/markdown url = https://github.com/easy-as-python/repo-man diff --git a/src/repo_man/cli.py b/src/repo_man/cli.py index e1323a2..620d45e 100644 --- a/src/repo_man/cli.py +++ b/src/repo_man/cli.py @@ -4,12 +4,12 @@ from repo_man.commands.add import add from repo_man.commands.edit import edit -from repo_man.commands.flavors import flavors from repo_man.commands.implode import implode from repo_man.commands.init import init from repo_man.commands.list_repos import list_repos from repo_man.commands.remove import remove from repo_man.commands.sniff import sniff +from repo_man.commands.types import types from repo_man.consts import REPO_TYPES_CFG @@ -27,7 +27,7 @@ def cli(context: click.Context) -> None: # pragma: no cover def main() -> None: # pragma: no cover cli.add_command(add) cli.add_command(edit) - cli.add_command(flavors) + cli.add_command(types) cli.add_command(implode) cli.add_command(init) cli.add_command(list_repos) diff --git a/src/repo_man/commands/flavors.py b/src/repo_man/commands/types.py similarity index 89% rename from src/repo_man/commands/flavors.py rename to src/repo_man/commands/types.py index 33d1f35..db8107d 100644 --- a/src/repo_man/commands/flavors.py +++ b/src/repo_man/commands/types.py @@ -8,7 +8,7 @@ @click.command @click.argument("repo", type=click.Path(exists=True, file_okay=False)) @pass_config -def flavors(config: configparser.ConfigParser, repo: str) -> None: +def types(config: configparser.ConfigParser, repo: str) -> None: """List the configured types for a repository""" ensure_config_file_exists() diff --git a/test/test_flavors.py b/test/test_types.py similarity index 75% rename from test/test_flavors.py rename to test/test_types.py index 88ca40b..3f616cb 100644 --- a/test/test_flavors.py +++ b/test/test_types.py @@ -4,19 +4,19 @@ import click -from repo_man.commands.flavors import flavors +from repo_man.commands.types import types -def test_flavors_clean(runner: click.testing.CliRunner, get_config: Callable[[], configparser.ConfigParser]) -> None: +def test_types_clean(runner: click.testing.CliRunner, get_config: Callable[[], configparser.ConfigParser]) -> None: with runner.isolated_filesystem(): Path("some-repo").mkdir() config = get_config() - result = runner.invoke(flavors, ["some-repo"], obj=config) + result = runner.invoke(types, ["some-repo"], obj=config) assert result.exit_code == 1 assert result.output == "No repo-man.cfg file found.\n" -def test_flavors_when_configured( +def test_types_when_configured( runner: click.testing.CliRunner, get_config: Callable[[], configparser.ConfigParser] ) -> None: with runner.isolated_filesystem(): @@ -36,12 +36,12 @@ def test_flavors_when_configured( ) config = get_config() - result = runner.invoke(flavors, ["some-repo"], obj=config) + result = runner.invoke(types, ["some-repo"], obj=config) assert result.exit_code == 0 assert result.output == "foo\n" -def test_flavors_when_not_configured( +def test_types_when_not_configured( runner: click.testing.CliRunner, get_config: Callable[[], configparser.ConfigParser] ) -> None: with runner.isolated_filesystem(): @@ -57,12 +57,12 @@ def test_flavors_when_not_configured( ) config = get_config() - result = runner.invoke(flavors, ["some-repo"], obj=config) + result = runner.invoke(types, ["some-repo"], obj=config) assert result.exit_code == 0 assert result.output == "" -def test_flavors_when_ignored( +def test_types_when_ignored( runner: click.testing.CliRunner, get_config: Callable[[], configparser.ConfigParser] ) -> None: with runner.isolated_filesystem(): @@ -78,6 +78,6 @@ def test_flavors_when_ignored( ) config = get_config() - result = runner.invoke(flavors, ["some-repo"], obj=config) + result = runner.invoke(types, ["some-repo"], obj=config) assert result.exit_code == 0 assert result.output == ""