diff options
| -rw-r--r-- | doc/proposals/2022-04-restructure-repositories.md | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/doc/proposals/2022-04-restructure-repositories.md b/doc/proposals/2022-04-restructure-repositories.md new file mode 100644 index 0000000..6a9785f --- /dev/null +++ b/doc/proposals/2022-04-restructure-repositories.md @@ -0,0 +1,109 @@ +# Background + +Current repository structure at git.sigsum.org: + + $ tree -L 2 + . + ├── research + │ └── README.md + ├── sigsum + │ ├── archive + │ ├── doc + │ ├── hugo + │ ├── issues + │ ├── LICENSE + │ └── README.md + ├── sigsum-lib-go + │ ├── cmd + │ ├── go.mod + │ ├── issues + │ ├── LICENSE + │ ├── pkg + │ └── README.md + ├── sigsum-log-go + │ ├── cmd + │ ├── go.mod + │ ├── go.sum + │ ├── integration + │ ├── issues + │ ├── LICENSE + │ ├── pkg + │ └── README.md + ├── sigsum-tools-go + │ ├── cmd + │ ├── go.mod + │ ├── go.sum + │ ├── LICENSE + │ ├── pkg + │ └── README.md + ├── sigsum-witness-py + │ ├── issues + │ ├── LICENSE + │ ├── README.md + │ └── sigsum-witness.py + ├── sysadm-tickets + │ └── README + └── testing + ├── cmd + ├── hello + └── hi + +Here's what we don't like about the current structure: + + a) "sigsum" is not an intuitive name for documentation, notes, etc. + It hogs the top-most namespace and is inconsistent compared to other + repos (could be "sigsum-docs"). + + b) "sigsum" in all repo names is redundant. We already have all + repositories grouped at git.sigsum.org. Go module names have + redundancy too (git.sigsum.org/sigsum-lib-go). + + c) unclear where everything "not log server and not sigsum lib" + should be placed. Both now and as we keep adding more tools and + other running components like monitors. + +# Proposal + + 1. Keep "sigsum" repo name. We shared many links to this + repository, avoid breakage. + + 2. Move towards generic repositories, per language. + + - sigsum-go, "lib + tools that in the long run don't pull in the whole world" + - log-go, "depends on sigsum-go, pulls in other log server specific stuff too" + - sigsum-py, "witness + tools" + + 3. Remove repos "research" and "sysadm-tickets". No use or planned usage. + +Connecting this to the problems we had with the current repo structure: + + c) Rule of thumb is to place <lang> stuff in sigsum-<lang>. If + there is a reason not to, break it out into a separate repo without + "sigsum" in the name. E.g., log-go and monitor-go, both of which + will likely have to be more permissive about dependencies. It is + crusial that generic repos are easy to use, reuse, pull-in, review, + and maintain. + + b) Fixed to some extent. One strength of the new structure is that, + e.g., sigsum-go signals that "this is where you should look for + sigsum stuff in Go". We expect that most newcomers will be more + interested in the lib or tools rather than Trillian stuff. If you + are looking for "not the generic stuff", you probably know where to + go already. + + a) Not fixed. There will however be relatively few repositories + that don't have a language ending (-go, -py, etc). This likely + signals that "this is a sigsum portal". This is further mitigated + by good repo descriptions on the listing at git.sigsum.org. + +The plan is to do the above restructuring after our v0 API changes are in place. + +# Examples + +An import in log-go: + + import "git.sigsum.org/sigsum-go/pkg/types" + +Installing the sigsum tool: + + $ go install git.sigsum.org/sigsum-go/cmd/sigsum@latest |