diff options
Diffstat (limited to 'docs/markdown/Adding-new-projects-to-wrapdb.md')
| -rw-r--r-- | docs/markdown/Adding-new-projects-to-wrapdb.md | 146 |
1 files changed, 94 insertions, 52 deletions
diff --git a/docs/markdown/Adding-new-projects-to-wrapdb.md b/docs/markdown/Adding-new-projects-to-wrapdb.md index 832f803..c79cfd3 100644 --- a/docs/markdown/Adding-new-projects-to-wrapdb.md +++ b/docs/markdown/Adding-new-projects-to-wrapdb.md @@ -1,84 +1,120 @@ -# Adding new projects to wrap +# Adding new projects to WrapDB -**If you don't have permissions to do something on this page, please - open issue against https://github.com/mesonbuild/wrapweb/issues to - let us know that you want to start new project.** -## Overview +## How it works -The wrap provider service is a simple web service that makes it easy -to download build definitions for projects. It works 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. +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. -## Creator script +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. + +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`. + +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. + +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. -The WrapDB repository has a [helper -script](https://github.com/mesonbuild/wrapweb/blob/master/mesonwrap.py) -to generate new repositories, verify them and update them. The documentation below roughly explains -what it does to create a new wrap repository using plain shell commands. +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 Wrapped subprojects are used much like external dependencies. Thus -they should have the same name as the upstream projects. If the -project provides a pkg-config file, then the repository name should be +they should have the same name as the upstream projects. + +If the project provides a pkg-config file, then the repository 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 named plain `ogg`. -## Adding new project to the Wrap provider service +If there is no a pkg-config file, the name the project uses/promotes should be used, +lowercase only (Catch2 -> catch2). -Each project gets its own repo. It is initialized like this: +## How to contribute a new wrap - git init - git add readme.txt - git add LICENSE.build - git commit -a -m 'Create project foobar' - git remote add origin <repo url> - git push -u origin master +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 provided. -Note that this is the *only* commit that will ever be made to master branch. All other commits are done to branches. +### Request a new repository or branch -Repo names must fully match this regexp: `[a-z0-9._]+`. +Create an issue on the [wrapweb bug tracker](https://github.com/mesonbuild/wrapweb/issues) +using *Title* and *Description* below as a template. -## Adding a new branch to an existing project +*Title:* `new wrap: <project_name>` -Create a new branch whose name matches the upstream release number. +*Description:* +``` +upstream url: <link_to_updastream> +version: <version_you_have_a_wrap_for> +``` - 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) +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. -Branch names must fully match this regexp: `[a-z0-9._]+`. +### Add a new wrap -## Adding a new release to an existing branch +First you need to fork the repository to your own page. +Then you can create the first Wrap commit that usually looks something like this. -Here is where the magic happens. 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. +``` +tar xzf libfoo-1.0.0.tar.gz +git clone -b 1.0.0 git@github.com:yourusername/libfoo.git tmpdir +mv tmpdir/.git libfoo-1.0.0 +rm -rf tmpdir +cd libfoo-1.0.0 +git reset --hard +emacs upstream.wrap meson.build +<verify that your project builds and runs> +git add upstream.wrap meson.build +git commit -a -m 'Add wrap files for libfoo-1.0.0' +git push origin 1.0.0 +``` -Note that your Git repo 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. +Now you should create a pull request on GitHub. Remember to create it against the +correct branch rather than master (`1.0.0` branch in this example). GitHub should do +this automatically. -First you need to fork the repository to your own page. Then you can create the first Wrap commit that usually looks something like this. +## What is done by WrapDB maintainers - tar xzf libfoo_1.0.0.tar.gz - git clone -b 1.0.0 git@github.com:yourusername/libfoo.git tmpdir - mv tmpdir/.git libfoo-1.0.0 - rm -rf tmpdir - cd libfoo-1.0.0 - git reset --hard - emacs upstream.wrap meson.build - <verify that your project builds and runs> - git add upstream.wrap meson.build - git commit -a -m 'Create wrap files for libfoo-1.0.0.' - git push origin 1.0.0 +### Adding new project to the Wrap provider service -Now you can file a merge request. Remember to file it against branch -1.0.0 rather than master. GitHub should do this automatically. +Each project gets its own repo. It is initialized like this: + +``` +git init +git add readme.txt +git add LICENSE.build +git commit -a -m 'Create project foobar' +git remote add origin <repo url> +git push -u origin master +``` + +Note that this is the *only* commit that will ever be made to master branch. All other commits are done to branches. + +Repo names must fully match this regexp: `[a-z0-9._]+`. + +### 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 @@ -93,6 +129,12 @@ to functionality. All such changes must be submitted to upstream. You may also host your own Git repo with the changes if you wish. The Wrap system has native support for Git subprojects. +## Creator script + +The WrapDB repository has a +[helper script](https://github.com/mesonbuild/wrapweb/blob/master/mesonwrap.py) +to generate new repositories, verify them and update them. + ## Reviewing wraps See [Wrap review guidelines](Wrap-review-guidelines.md). |