Skip to content

Latest commit

 

History

History
68 lines (47 loc) · 5.39 KB

CONTRIBUTING.md

File metadata and controls

68 lines (47 loc) · 5.39 KB
Raw

Contributing to Yggdrasil

Information for contributors

Yggdrasil is a collection of recipes to build binary packages, saved in files called build_tarballs.jl.

If you are new to BinaryBuilder, please read its documentation. In particular, the section Project flow presents different ways you can use BinaryBuilder to create a new build_tarballs.jl script or edit an existing one. Note that the wizard is a convenient tool to get started with BinaryBuilder, but it does not give you access to all the options you can use in a manual build_tarball.jl file. Also, for an already existing recipe you are advised to edit it manually rather than starting from scratch with the wizard.

If you want to submit a new package or update an existing one, you always have to open a pull request to the Yggdrasil repository on GitHub to create or modify the build_tarballs.jl file of the package you are interested in. Note that it is important to modify the build_tarballs.jl file of your package, or any other file in the same directory or one of its subdirectories: Yggdrasil CI workflow uses the modified build_tarballs.jl file to identify which package to rebuild, if no build_tarballs.jl (or any other file in its subdirectories) is touched, no build will happen. Make sure not to mistype the name of the file.

If you are submitting a recipe for a new package, follow the suggestions in the Building Packages page of BinaryBuilder documentation.

If you want to build a new version of an existing package, you can open a pull request which updates the sources and the version number of the package as appropriate. In most cases it is sufficient to change only these two properties of the recipe, but sometimes more work will be required if there are any changes in the build system (e.g. changed dependencies, or options for the build system) or bugs in the source code to deal with.

Recommendations and tips about commit messages

Yggdrasil is a collection of recipes for hundreds of different packages. To make it easier to browse through commits history and list of pull requests, please use descriptive commit messages and include in the title of the commit and of pull requests the name of the package you are touching, for example:

[XGBoost] Update to v1.7.3

Titles like

Update build_tarballs.jl

or

Build v1.7.3

are not descriptive (virtually all pull requests update a file called build_tarballs.jl) or they do not make it clear what package they refer to.

Special keywords in commit messages

There are some special tags that can be used anywhere in a commit message to do something special. Yggdrasil currently uses Azure Pipelines for CI, this allows using some special keywords to allow skipping CI on commits, like [skip ci] or [skip azp]. However these have effect only if the keywords appear in the commit message of the tip of branch which triggered the workflow: in pull requests the tip of the branch is always the merge commit automatically generated by GitHub, so that [skip ci] in your commit will be ignored when running CI for a pull request. Instead, this does have effect if the keyword is included in the commit which triggers CI on the default branch, for example if the pull request has been squash-merged by a maintainer.

Another special keyword which is [skip build]. This is a two-fold effect:

  • in pull requests, a build of the touched packages will not be performed
  • for commits pushed to the default branch, a new build of the touched packages will not be performed but a new version of the correspoding JLL packages will be published, using as artifacts those from the latest registered versions of the packages (the build number will be increased by one).

Information for maintainers

Here are some recommendations for Yggdrasil maintainers:

  • before merging a pull request, make sure the log of the build does not contain important warnings or error messages such as
    • missing license file. This is reported as an error in CI log during audit but it is not as a fatal error which would prevent successful build
    • "Linked library <LIBRARY NAME> could not be resolved and could not be auto-mapped"
  • make sure a pull request is not changing julia compat bounds without changing the version number of the package. This is particularly important when building an existing package for the first time for aarch64-darwin or armv6l-linux
  • make sure dependencies of packages with known incompatibilities are pinned correctly
  • always squash and merge pull requests, to keep history short and linear. There is little need to preserve full history of individual pull requests. This also makes sure special keywords in commit messages are part of the commit which triggers the CI workflow and so they can have effect.