Add weld-metadata WARP (work in progress!)HEADmaster

Starting to try to specify what the metadata should look like.

1 files changed, 145 insertions, 0 deletions

diff --git a/warp/0002-weld-metadata.md b/warp/0002-weld-metadata.md
new file mode 100644
index 0000000..d4c988a
--- /dev/null
+++ b/warp/0002-weld-metadata.md
@@ -0,0 +1,145 @@
+# weld-pkg-metadata
+
+| WARP     | 2
+|----------|--------------------------------------------------------
+| Title    | Weld Package Metadata
+| Author   | Will Woods
+| Type     | Standards
+| Proposed | 21 Jan 2016
+| Status   | Draft
+
+----
+
+# Summary
+[summary]: #summary
+
+This document describes the package metadata used by the Weld project.
+
+# Motivation
+[motivation]: #motivation
+
+The heart of a Linux distribution is its package metadata. [RPM]-based
+distributions have [spec files], [dpkg]-based distributions
+have the [`debian/` directory], [Gentoo] has [ebuild] files, and so on.
+
+Since everything produced by a Linux distribution is derived from this metadata,
+it's crucial to the health of the project. Weld's metadata is designed with
+the following goals in mind:
+
+1. **Simple**: the files should be short and (mostly) human-readable.
+2. **Flexible**: we should be able to add new fields when needed.
+3. **Powerful**: the metadata should be able to express everything currently
+   handled by [spec files] in Fedora.
+4. **Customizable**: it should be easy for a Weld user to fork and build their
+   own variant, with different build flags, alternative implementations, etc.
+
+[RPM]: http://rpm.org/
+[spec files]: http://www.rpm.org/max-rpm/ch-rpm-inside.html
+[dpkg]: https://en.wikipedia.org/wiki/Dpkg
+[`debian/` directory]: https://www.debian.org/doc/manuals/maint-guide/dreq.en.html
+[Gentoo]: https://www.gentoo.org/
+[ebuild]: https://devmanual.gentoo.org/ebuild-writing/index.html
+
+[YUM metadata]: https://en.opensuse.org/openSUSE:Standards_Rpm_Metadata
+[Fedora RPM Guide]: https://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-specfiles.html
+
+# Specification
+[spec]: #spec
+
+## File format
+
+Weld's metadata files are in [TOML] format, with sections, keys, and values
+to be described below.
+
+[TOML]: https://github.com/toml-lang/toml
+
+## File names and repo layout
+
+The files are named `<package>.weld`, and they are kept in a git repo named
+`weld-dist`. Related packages may grouped into subdirectories - for example,
+`gfx/wayland.weld` or `dev/gcc.weld`.
+
+## File sections
+
+### `[upstream]`
+
+The `[upstream]` section describes where the upstream code can be found, what
+format it's in, and other metadata pertaining to finding and fetching code
+from the upstream developers.
+
+#### `homepage = <http-url>`
+
+_Optional._ Gives a `http` or `https` URL to the upstream project's homepage.
+
+#### `vcs = <url>`
+
+Gives the URL of the upstream's version control system.
+
+#### `tarball = <url>`
+
+Gives the URL to a tarball of released sources.
+
+The escape sequence `{version}` can be used as a placeholder for the version
+string.
+
+### `[build]`
+
+The `[build]` section describes how to build the software
+
+# Rationale
+[rationale]: #rationale
+
+## Considerations
+[considerations]: #considerations
+
+One of the major goals for Weld is that package metadata and build instructions
+should be encoded as _data_, not _code_ - in other words: no shell scripts
+unless absolutely necessary.
+
+[TOML] was chosen because of its clean, simple syntax and unambiguous parsing
+rules. This allows `.weld` files to be read and written easily in nearly any
+popular programming language.
+
+## Alternatives
+[alternatives]: #alternatives
+
+### `spec`
+
+* Under-documented - where's the specification for spec files?
+* Inflexible - no `TestRequires`, and no easy way to add it
+* Opaque - impossible to tell what scriptlets will do, how long they will take,
+  how much disk they might use, etc.
+
+### `debian/*`
+
+TODO
+
+### `ebuild`
+
+Also TODO
+
+### `Cargo.toml` and `Cargo.lock`
+
+TODO. A lot of what's going on here is inspired by (or coincidentally
+similar to) [Cargo] and [Cargo manifest]s; look closer at it.
+
+[Cargo]: http://doc.crates.io/guide.html
+[Cargo manifest]: http://doc.crates.io/manifest.html
+
+## Unresolved Questions
+[questions]: #questions
+
+* How are we gonna create the initial set of `.weld` files?
+* What escape sequences do we want/need?
+  * And what form should those take? `{name}`, `%n`, ..?
+* If we're gonna talk about dependencies we need a spec for package / binary
+  match expressions
+  * like RPM version expressions (`xz >= 5.2.0`)
+  * or Cargo version expressions ()
+
+# Copyright
+[copyright]: #copyright
+
+This work is licensed under the Creative Commons Attribution 4.0 International
+License. To view a copy of this license, visit
+http://creativecommons.org/licenses/by/4.0/.