Update wrap documentation to describe new submission process

2 files changed, 57 insertions, 243 deletions

diff --git a/docs/markdown/Adding-new-projects-to-wrapdb.md b/docs/markdown/Adding-new-projects-to-wrapdb.md
index 51a0d71..7b51c9a 100644
--- a/docs/markdown/Adding-new-projects-to-wrapdb.md
+++ b/docs/markdown/Adding-new-projects-to-wrapdb.md
@@ -3,50 +3,48 @@
 
 ## How it works
 
-Each wrap repository has a master branch with only one initial commit
-and *no* wrap files. And that is the only commit ever made on that
-branch.
-
-For every release of a project a new branch is created. The new branch
-is named after the the upstream release number (e.g. `1.0.0`). This
-branch holds a wrap file for this particular release.
+New wraps must be submitted as a working subproject to the [wrapdb
+repository](https://github.com/mesonbuild/wrapdb).
 
 There are two types of wraps on WrapDB - regular wraps and wraps with
-Meson build definition patches. A wrap file in a repository on WrapDB
-must have a name `upstream.wrap`.
+Meson build definition patches.
 
 Wraps with Meson build definition patches work in much the same way as
 Debian: we take the unaltered upstream source package and add a new
-build system to it as a patch. These build systems are stored as Git
-repositories on GitHub. They only contain build definition files. You
-may also think of them as an overlay to upstream source.
+build system to it as a patch. These build systems are stored as a
+subdirectory of subprojects/packagefiles/. They only contain build
+definition files. You may also think of them as an overlay to upstream
+source.
+
+Wraps without Meson build definition patches only contain the wrap
+metadata describing how to fetch the project
 
-Whenever a new commit is pushed into GitHub's project branch, a new
-wrap is generated with an incremented version number. All the old
-releases remain unaltered. New commits are always done via GitHub
-merge requests and must be reviewed by someone other than the
-submitter.
+Whenever a new release is pushed into the wrapdb, a new tag is
+generated with an incremented version number, and a new release is
+added to the wrapdb API listing. All the old releases remain
+unaltered. New commits are always done via GitHub merge requests and
+must be reviewed by someone other than the submitter.
 
 Note that your Git repo with wrap must not contain the subdirectory of
 the source release. That gets added automatically by the service. You
 also must not commit any source code from the original tarball into
 the wrap repository.
 
-## Choosing the repository name
+## Choosing the wrap name
 
 Wrapped subprojects are used much like external dependencies. Thus
 they should have the same name as the upstream projects.
 
-NOTE: Repo names must fully match this regexp: `[a-z0-9._]+`.
+NOTE: Wrap names must fully match this regexp: `[a-z0-9._]+`.
 
-If the project provides a pkg-config file, then the repository name
+If the project provides a pkg-config file, then the wrap name
 should be the same as the pkg-config name. Usually this is the name of
 the project, such as `libpng`. Sometimes it is slightly different,
 however. As an example the libogg project's chosen pkg-config name is
-`ogg` instead of `libogg`, which is the reason why the repository is
+`ogg` instead of `libogg`, which is the reason why the wrap is
 named plain `ogg`.
 
-If there is no a pkg-config file, the name the project uses/promotes
+If there is no pkg-config file, the name the project uses/promotes
 should be used, lowercase only (Catch2 -> catch2).
 
 If the project name is too generic or ambiguous (e.g. `benchmark`),
@@ -56,85 +54,20 @@ consider using `organization-project` naming format (e.g.
 ## How to contribute a new wrap
 
 If the project already uses Meson build system, then only a wrap file
-- `upstream.wrap` should be provided. In other case a Meson build
-definition patch - a set of `meson.build` files - should be also
+`project.wrap` should be provided. In other case a Meson build
+definition patch - a set of `meson.build` files - should also be
 provided.
 
-### Request a new repository
-
-*Note:* you should only do this if you have written the build files
-and want to contribute them for inclusion to WrapDB. The maintainers
-have only limited reesources and unfortunately can not take requests
-to write Meson build definitions for arbitrary projects.
-
-The submission starts by creating an issue on the [wrapdb bug
-tracker](https://github.com/mesonbuild/wrapdb/issues) using *Title*
-and *Description* below as a template.
-
-*Title:* `new wrap: <project_name>`
-
-*Description:*
-```
-upstream url: <link_to_updastream>
-version: <version_you_have_a_wrap_for>
-```
-
-Wait until the new repository or branch is created. A link to the new
-repository or branch will be posted in a comment to this issue. After
-this you can createa a merge request in that repository for your build
-files.
-
-NOTE: Requesting a branch is not necessary. WrapDB maintainer can
-create the branch and modify the PR accordingly if the project
-repository exists.
-
 ### Creating the wrap contents
 
-Setting up the contents might seem a bit counterintuitive at first.
-Just remember that the outcome needs to have one (and only one) commit
-that has all the build definition files (i.e. `meson.build` and
-`meson_options.txt` files) and _nothing else_. It is good practice to
-have this commit in a branch whose name matches the release as
-described above.
-
-First you need to fork the repository to your own page using GitHub's
-fork button. Then you can clone the repo to your local machine.
-
-
-```
-git clone git@github.com:yourusername/libfoo.git foo-wrap
-```
-
-Create a new branch for your work:
-
-```
-git checkout -b 1.0.0
-```
-
-If you are adding new changes to an existing branch, leave out the
-`-b` argument.
-
-Now you need to copy the source code for the original project to this
-directory. If you already have it extracted somewhere, you'd do
-something like this:
-
-```
-cd /path/to/source/extract/dir
-cp -r * /path/to/foo-wrap
-```
-
-Now all the files should be in the wrap directory. Do _not_ add them
-to Git, though. Neither now or at any time during this process. The
-repo must contain only the newly created build files.
-
-New release branches require an `upstream.wrap` file, so create one if
+New release branches require a `project.wrap` file, so create one if
 needed.
 
 ```
 ${EDITOR} upstream.wrap
 ```
 
-The file format is simple, see any existing wrapdb repo for the
+The file format is simple, see any existing wrapdb subproject for the
 content. The checksum is SHA-256 and can be calculated with the
 following command on most unix-like operating systems:
 
@@ -167,78 +100,47 @@ variable of that name is not defined, Meson will exit with a hard
 error. For further details see [the main Wrap
 manual](Wrap-dependency-system-manual.md).
 
-Now you can create the build files and work on them until the project
-builds correctly.
+Now you can create the build files, if the upstream project does not
+contain any, and work on them until the project builds correctly.
+Remember that all files go in the directory
+`subprojects/packagefiles/<project-name>`.
 
 ```
 ${EDITOR} meson.build meson_options.txt
 ```
 
-When you are satisfied with the results, add the build files to Git
-and push the result to GitHub.
+In order to apply the locally added build files to the upstream
+release tarball, the `wrap-file` section must contain a
+`patch_directory` property naming the subdirectory in
+subprojects/packagefiles/ with the build files inside, as this is
+central to the way the wrapdb works. It will be used by the wrapdb
+meson.build, and when a release is created, the files from this
+directory will be converted into an archive and a patch_url will be
+added to the wrap file.
+
+When you are satisfied with the results, add the build files to Git, update
+releases.json as described in
+[README.md](https://github.com/mesonbuild/wrapdb#readme), and push the result
+to GitHub.
 
 ```
 <verify that your project builds and runs>
-git add upstream.wrap meson.build
+git add releases.json subprojects/project.wrap subprojects/packagefiles/project/
 git commit -a -m 'Add wrap files for libfoo-1.0.0'
-git push -u origin 1.0.0
+git push -u origin libfoo
 ```
 
-Now you should create a pull request on GitHub. Try to create it
-against the correct branch rather than master (`1.0.0` branch in this
-example). GitHub should do this automatically.
-
-If the branch doesn't exist file a pull request against master.
-WrapDB maintainers can fix it before merging.
+Now you should create a pull request on GitHub. 
 
 If packaging review requires you to do changes, use the `--amend`
-argument to `commit` so that your branch will continue to have only
-one commit.
+argument to `commit` so that your branch will have only one commit.
 
 ```
 ${EDITOR} meson.build
-git commit -a --amend
+git commit -u --amend
 git push --force
 ```
 
-### Request a new release version to an existing repository
-
-Adding new releases to an existing repo is straightforward. All you
-need to do is to follow the rules discussed above but when you create
-the merge request, file it against the master branch. The repository
-reviewer will create the necessary branch and retarget your merge
-request accordingly.
-
-## What is done by WrapDB maintainers
-
-[mesonwrap tools](Wrap-maintainer-tools.md) must be used for the tasks
-below.
-
-### Adding new project to the Wrap provider service
-
-Each project gets its own repo. It is initialized like this:
-
-```
-mesonwrap new_repo --homepage=$HOMEPAGE --directory=$NEW_LOCAL_PROJECT_DIR $PROJECT_NAME
-```
-
-The command creates a new repository and uploads it to GitHub.
-
-`--version` flag may be used to create a branch immediately.
-
-### Adding a new branch to an existing project
-
-Create a new branch whose name matches the upstream release number.
-
-```
-git checkout master
-git checkout -b 1.0.0
-git push origin 1.0.0
-(or from GitHub web page, remember to branch from master)
-```
-
-Branch names must fully match this regexp: `[a-z0-9._]+`.
-
 ## Changes to original source
 
 The point of a wrap is to provide the upstream project with as few
@@ -259,9 +161,15 @@ passing it is a requirement for merging. Therefore it is highly
 recommended that you run the validation checks yourself so you can fix
 any issues faster.
 
-Instructions on how to install and run the review tool can be found on
-the [Wrap review guidelines page](Wrap-review-guidelines.md).  If your
-submission is merge request number 5 for a repository called `mylib`,
-then you'd run the following command:
+You can test the wrap itself with the following commands:
+
+    meson subprojects purge --confirm
+    meson setup builddir/ -Dwraps=<project-name>
+
+The first command is to ensure the wrap is correctly fetched from the
+latest packagefiles. The second command configures meson and selects a
+set of subprojects to enable.
 
-    mesonwrap review --pull-request 5 mylib
+The Github project contains automatic CI on pushing to run the project
+and check the metadata for obvious mistakes. This can be checked from
+your fork before submitting a PR.
diff --git a/docs/markdown/Wrap-review-guidelines.md b/docs/markdown/Wrap-review-guidelines.md
deleted file mode 100644
index 670baa6..0000000
--- a/docs/markdown/Wrap-review-guidelines.md
+++ /dev/null
@@ -1,94 +0,0 @@
-# Wrap review guidelines
-
-In order to get a package in the Wrap database it must be reviewed and
-accepted by someone with admin rights. Here is a list of items to
-check in the review. If some item is not met it does not mean that the
-package is rejected. What should be done will be determined on a
-case-by-case basis. Similarly meeting all these requirements does not
-guarantee that the package will get accepted. Use common sense.
-
-## Setting up the tools
-
-The [mesonwrap repository](https://github.com/mesonbuild/mesonwrap)
-provides tools to maintain the WrapDB. Read-only features such can be
-used by anyone without Meson admin rights.
-
-## Personal access token
-
-Some tools require access to the Github API. A [personal access
-token](https://github.com/settings/tokens) may be required if the
-freebie Github API quota is exhausted. `public_repo` scope is required
-for write operations.
-
-```
-$ cat ~/.config/mesonwrap.ini
-[mesonwrap]
-github_token = <github token>
-```
-
-## Setting up the review tooling
-
-The [Mesonwrap](https://github.com/mesonbuild/mesonwrap/) repository
-contains review tooling. It is used to do the actual review, but
-submitters can also use it to check their MRs. All issues reported by
-the tool must be fixed, so using the tool can speed up the review
-process considerably.
-
-The tool has some dependencies that are not available in all Linux
-distributions. Thus using a Python
-[Virtualenv](https://virtualenv.pypa.io/en/stable/). The tool can be
-installed with the following commands.
-
-```
-git clone https://github.com/mesonbuild/mesonwrap.git
-cd mesonwrap
-python3 -m venv venv
-bash
-source venv/bin/activate
-pip install -r requirements.txt
-# You may need to install Meson and Ninja here as well depending on your setup
-python3 setup.py install
-mesonwrap review <see arguments below>
-exit             <when you are finished>
-```
-
-## Reviewing code
-
-```
-mesonwrap review zlib --pull-request=1 [--approve]
-```
-
-Since not every check can be automated please pay attention to the
-following during the review:
-
-- Download link points to an authoritative upstream location.
-- Version branch is created from master.
-- Except for the existing code, `LICENSE.build` is mandatory.
-- `project()` has a version and it matches the source version.
-- `project()` has a license.
-- Complex `configure_file()` inputs are documented.
-  If the file is a copy of a project file make sure it is clear what was changed.
-- Unit tests are enabled if the project provides them.
-- There are no guidelines if `install()` is a good or a bad thing in wraps.
-- If the project can't be tested on the host platform consider using the `--cross-file` flag.
-  See [the issue](https://github.com/mesonbuild/mesonwrap/issues/125).
-
-Encourage wrap readability. Use your own judgement.
-
-## Approval
-
-If the code looks good use the `--approve` flag to merge it.
-The tool automatically creates a release.
-
-If you need to create a release manually (because, for example, a MR
-was merged by hand), the command to do it is the following:
-
-```shell
-mesonwrap publish reponame version
-```
-
-An example invocation would look like this:
-
-```shell
-mesonwrap publish expat 2.2.9
-```