From b664f0cd3918390b665a16090734a358272a35a3 Mon Sep 17 00:00:00 2001 From: Paul Jolly Date: Thu, 28 Sep 2023 13:26:00 +0100 Subject: [PATCH] internal/mod: kick off WIP doc to track FAQs, points to document Start a WIP doc which captures things we need to document, questions we need to answer etc as part of any modules implementation. Doing this as part of the main CUE repo means we can add such points/questions alongside the changes the pompt them. Using a WIP markdown file for now also punts the decision on where the end documentation actually ends up. Signed-off-by: Paul Jolly Change-Id: I8c973dadd1ed3198008f3a895913865185f85544 Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1170070 TryBot-Result: CUEcueckoo Unity-Result: CUE porcuepine Reviewed-by: Roger Peppe --- internal/mod/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 internal/mod/README.md diff --git a/internal/mod/README.md b/internal/mod/README.md new file mode 100644 index 00000000000..c90077b21eb --- /dev/null +++ b/internal/mod/README.md @@ -0,0 +1,22 @@ +## WIP Modules FAQ/README/etc + +This is a WIP file in which we capture aspects of the modules implementation +that need documenting. Some take the form of FAQ-like questions, others are +simply details which we need to ensure are documented. Some of the points +listed below could be part of a modules reference doc, others a modules FAQ... +We don't seek to make a decision on what docs/FAQs etc should exist, just use +this opportunity to capture the bits that need coverage. + +Some of the questions below are presented with answers, many are just left here +as a TODO. + +The goal of this doc is to capture things in a central VCS-based file, alongside +the code that "raises" the question/similar. + +* Documentation around defaulting the value of `CUE_REGISTRY` (or whatever we + call it) to the central registry. +* Document that `pkg`, `usr` and `gen` directories cannot co-exist with modules, + and make clear what users (especially of `gen`) should probably do instead. +* Document potential future vendor behaviour. +* Document what we mean by a "canonical" version, how this differs from a + "well-formed" version. Present examples of each.