From ec13f00a61d20a32d201f696b0bfa9826473a166 Mon Sep 17 00:00:00 2001 From: Dane Hillard Date: Tue, 7 Nov 2023 18:53:03 -0500 Subject: [PATCH] Add architecture decision records --- .adr-dir | 1 + CHANGELOG.md | 17 +++++++++++++ .../0001-record-architecture-decisions.md | 19 ++++++++++++++ ...a-versioning-during-initial-development.md | 25 +++++++++++++++++++ ...config-file-to-store-repository-flavors.md | 25 +++++++++++++++++++ docs/conf.py | 1 + docs/index.rst | 7 ++++++ setup.cfg | 12 +++++++++ src/repoman/cli.py | 3 +-- 9 files changed, 108 insertions(+), 2 deletions(-) create mode 100644 .adr-dir create mode 100644 CHANGELOG.md create mode 100644 docs/architecture/decisions/0001-record-architecture-decisions.md create mode 100644 docs/architecture/decisions/0002-use-alpha-versioning-during-initial-development.md create mode 100644 docs/architecture/decisions/0003-use-a-config-file-to-store-repository-flavors.md diff --git a/.adr-dir b/.adr-dir new file mode 100644 index 0000000..a180c8c --- /dev/null +++ b/.adr-dir @@ -0,0 +1 @@ +docs/architecture/decisions/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b970670 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,17 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +## [0.0.1] - 2023-11-07 + +### Added + +- List repositories configured with a given flavor +- List repositories configured with more than one flavor +- List repositories with no configured flavor +- List configured flavors diff --git a/docs/architecture/decisions/0001-record-architecture-decisions.md b/docs/architecture/decisions/0001-record-architecture-decisions.md new file mode 100644 index 0000000..fbc1769 --- /dev/null +++ b/docs/architecture/decisions/0001-record-architecture-decisions.md @@ -0,0 +1,19 @@ +# 1. Record architecture decisions + +Date: 2023-11-07 + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made on this project. + +## Decision + +We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). + +## Consequences + +See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools). diff --git a/docs/architecture/decisions/0002-use-alpha-versioning-during-initial-development.md b/docs/architecture/decisions/0002-use-alpha-versioning-during-initial-development.md new file mode 100644 index 0000000..47c4cc2 --- /dev/null +++ b/docs/architecture/decisions/0002-use-alpha-versioning-during-initial-development.md @@ -0,0 +1,25 @@ +# 2. Use alpha versioning during initial development + +Date: 2023-11-07 + +## Status + +Accepted + +## Context + +Semantic versioning is a (sometimes) helpful communication tool to help users know when to expect they'll need to respond to, or at least be aware of, changes that break an API. Semantic versioning communicates a different set of concepts altogether than calendar versioning, and although it leaves room for subjectivity and human error is currently the prevailing approach. + +During initial development of a project, many changes may be breaking changes. If semantic versioning is followed well during this phase, the outcome is a fast-increasing version number. By the time the project stabilizes, there may already have been tends or even hundreds of breaking changes. + +Choosing the right semantic version also carries a mild cognitive burden and can create points of drawn out discussion. Left to these devices, initial development can be slowed by too much back-and-forth. + +## Decision + +Use alpha versioning during initial development such that all versions are monotonically increasing versions of the form `0.0.XYZ`. + +## Consequences + +- Consumers won't know when a change is breaking, and should assume *every* change is breaking +- This decision will need to be amended once the project matures into a stable release pattern +- There is sometimes confusion about versions like `0.0.996` and people try to install `0.99.6` or similar instead diff --git a/docs/architecture/decisions/0003-use-a-config-file-to-store-repository-flavors.md b/docs/architecture/decisions/0003-use-a-config-file-to-store-repository-flavors.md new file mode 100644 index 0000000..1301300 --- /dev/null +++ b/docs/architecture/decisions/0003-use-a-config-file-to-store-repository-flavors.md @@ -0,0 +1,25 @@ +# 3. Use a configuration file to store repository flavors + +Date: 2023-11-07 + +## Status + +Accepted + +## Context + +Common approaches to tagging on file systems are filename embedding and sidecars[^1]. When working with repositories under version control, these approaches don't work well because they require changing file names or adding new files to the repository, both of which incur additional repository actions to commit, ignore, or otherwise manage the changes. Other approaches such as [macOS tags](https://support.apple.com/guide/mac-help/tag-files-and-folders-mchlp15236/mac) and [extended attributes](https://www.man7.org/linux/man-pages/man7/xattr.7.html) are either too platform-specific or don't work well at the command line. + +These approaches mainly seek to be able to abstract the tagging implementation completely from the consumer. The consumer using repo-man is trusted instead to know a bit about the tagging system because if they have the problems repo-man solves they're already more likely to care about or be accepting of a mild level of configuration burden. + +## Decision + +Use a separate configuration file for tagging directories. + +## Consequences + +- No repository has to know about the details of repo-man at all +- Consumers will need to know about and manage repo-man configuration, the burden of which can be mitigated by tooling +- The repo-man file is prone to loss because it isn't under version control + +[^1]: [https://unix.stackexchange.com/a/388201](https://unix.stackexchange.com/a/388201) diff --git a/docs/conf.py b/docs/conf.py index 28a70ed..0565739 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'myst_parser', 'sphinx.ext.intersphinx', 'sphinx.ext.autodoc', 'sphinx.ext.autodoc.typehints', diff --git a/docs/index.rst b/docs/index.rst index 407e946..8547428 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,13 @@ Manage repositories of different flavors. reference/modules +.. toctree:: + :glob: + :caption: Architecture decision records: + :hidden: + + architecture/decisions/* + 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. diff --git a/setup.cfg b/setup.cfg index e62633b..55fa2d6 100644 --- a/setup.cfg +++ b/setup.cfg @@ -9,7 +9,18 @@ author = Dane Hillard author_email = "Dane Hillard" license = MIT License license_files = LICENSE +project_urls = + Documentation=https://repo-man.readthedocs.org + Source=https://github.com/easy-as-python/repo-man + Tracker=https://github.com/easy-as-python/repo-man/issues classifiers = + Development Status :: 5 - Production/Stable + Intended Audience :: Developers + Programming Language :: Python + Programming Language :: Python :: 3.9 + Programming Language :: Python :: 3.12 + Programming Language :: Python :: 3 + Programming Language :: Python :: 3 :: Only License :: OSI Approved :: MIT License [options] @@ -31,6 +42,7 @@ console_scripts = [options.extras_require] docs = furo + myst-parser sphinx sphinx-autobuild diff --git a/src/repoman/cli.py b/src/repoman/cli.py index 7d07993..4608a69 100644 --- a/src/repoman/cli.py +++ b/src/repoman/cli.py @@ -100,9 +100,8 @@ def main(): check_if_allowed(path) parser = argparse.ArgumentParser( - prog="./thing", + prog="repoman", description="Manage repositories of different types", - epilog="Cool, man.", ) configure_arguments(parser)