Add architecture decision records (#6)

* Add architecture decision records

* Update version, changelog, versioning ADR

Author: daneah

.adr-dir

@@ -0,0 +1 @@
+docs/architecture/decisions/

CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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.2] - 2023-11-07
+
+### Fixed
+
+- Update help text to reflect repo-man program name
+- Remove useless help text epilog
+
+## [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

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).

docs/architecture/decisions/0002-use-alpha-versioning-during-initial-development.md

@@ -0,0 +1,26 @@
+# 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
+- Every released change during initial development will simply increase the last portion of the version string by one

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)

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',

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.

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = repo-man
-version = 0.0.1
+version = 0.0.2
 description = Manage repositories of different flavors.
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -9,7 +9,18 @@ author = Dane Hillard
 author_email = "Dane Hillard" <github@danehillard.com>
 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
 

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)