Virtualization
/
meson
mirror of https://gitlab.com/qemu-project/meson.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update wrap documentation to describe new submission process

This commit is contained in:
Eli Schwartz 2021-08-11 23:11:41 -04:00
parent cfc0a95c6f
commit bf1ae2c7f9
No known key found for this signature in database
GPG Key ID: CEB167EFB5722BD6
2 changed files with 57 additions and 243 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
docs/markdown/Adding-new-projects-to-wrapdb.md
View File

@ -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.
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.
Wraps without Meson build definition patches only contain the wrap
metadata describing how to fetch the project
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:
mesonwrap review --pull-request 5 mylib
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.
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.

94
docs/markdown/Wrap-review-guidelines.md
View File

@ -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
```