aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/proposals/2022-04-restructure-repositories.md109
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