design.md

@@ -18,34 +18,42 @@ This is a draft - comments/discussion/edits are **WELCOME**
 
 `apkg` should be replaceable. Projects following `apkg` conventions should be able to continue packaging (with few scripts of their own probably) even if they chose to drop `apkg`.
 
+
 ## Concepts
 
-* `archive` refers to archive containing project source code (also known as tarball).
-* `distro` refers to operating system distribution such as Debian, Fedora, Arch, NixOS, etc.
-* `repo` refers to `git` (or other VCS) repository containing project sources
-* `package` refers to a package archive accepted by a package manager of particular OS distribution
-* `package sources` refer to files needed in order to build a package. This varies a lot between distros, for example RPMs are built from a single `.src.rpm` source package while `.deb` packages are built from several files
+* `archive`: archive containing project source code (also known as tarball).
+* `distro`: operating system distribution such as Debian, Fedora, Arch, NixOS, etc.
+* `repo`: `git` (or other VCS) repository containing project sources
+* `package`: package archive accepted by a package manager of particular OS distribution
+* `source package`: files needed in order to build a package (this varies a lot between distros, for example RPMs are built from a single `.src.rpm` source package while `.deb` packages are built from several files)
+* `packaging style`: processes associated with packaging for specific family of distros (for example `deb` packaging style is used on Debian, Ubuntu, and their clones)
+* `packaging template`: files needed to build a source package; this could be called "packaging sources" but I suggest using "template" instead in order to avoid confusion with `source package`.
+
 
 ## Conventions
 
-`apkg` is to be invoked in a local `git` copy of a project to be packaged.
+`apkg` is to be invoked in a local `git` copy of a project to be packaged if applicable.
 
 `apkg` operates on a current `git` commit by default/unless specified otherwise. Behavior might differ between commits with and without version tag (such as `v1.0.0`) but operation and outputs must be consistent from user point of view and always carried out in context of respective upstream git commit.
 
 
 ### Input
 
-Current `git` repo is assumed to be a project to be packaged.
+Current repo is assumed to be a project to be packaged.
 
-Project at current `git` commit is a default input. Most operations should require clean `git` and refuse to run otherwise to prevent unexpected behavior based on local changes.
+Repo at current commit is a default input. Most operations should require clean `git` and refuse to run otherwise to prevent unexpected behavior based on local changes and/or overwriting local changes.
 
-Project `git` repo is expected to have a top-level `/distro` directory with individual directories containing distro-specific packaging files, for example:
+Project repo is expected to have a top-level `distro` directory containing all **input** files required for packaging. **`distro/` is strictly input-only directory.** Files there shouldn't ever by modified in-place during normal `apkg` operation (unless requested) and no additional files must be created there.
 
 ```
-project
-└── distro
+distro
+├── .apkg                  <- apkg configuration and other files such as custom plugins/packaging styles
+│   ├── config.yaml
+│   └── plugins
+├── common                 <- shared packaging files such as systemd services
+│   └── project.service
+└── pkg                    <- packaging templates - source packages are built from these files
     ├── arch
-    │   ├── install
     │   └── PKGBUILD
     ├── deb
     │   ├── changelog
@@ -54,15 +62,19 @@ project
     └── rpm
         └── project.spec
 ```
-This has few advantages over individual packaging directories directly in root as seen in the wild (`debian/`, `rpm/`, ..):
+
+This structure has few advantages over individual packaging directories directly in root as seen in the wild (`debian/`, `rpm/`, ..):
 
 * not spamming project root with multiple arbitrary directories (which might collide with existing dirs)
 * having all packaging files in one place (easier to notice/update all of them, nicer diffs, ...)
 * in case of `debian/`, not colliding with downstream `debian/` dir - projects are recommended not to include such directory in upstream tree
 
-Optional `distro/apkg.conf` configuration file might be introduced to allow customization for non-standard setups.
+Furthermore, having packaging templates in a dedicated `distro/pkg/` directory has following advantages as opposed to having them directly in `distro/`:
+
+* `distro/` can contain arbitrary distro-related dirs as needed without affecting template discovery
+* every `distro/pkg/*` dir is expected to be a valid packaging template - this makes discovery and management much easier in comparison to a case where some dirs are templates and some dirs are other unrelated things.
 
-**TODO**: carefully consider name for top level packaging directory (now `distro`)
+`distro/.apkg/config.yaml` configuration file will be used to define/override project-specific behavior.
 
 
 ### Output