Skip to content

Latest commit

 

History

History
61 lines (42 loc) · 5.25 KB

CONTRIBUTING.md

File metadata and controls

61 lines (42 loc) · 5.25 KB
Raw

Thanks for your interest in the Alire project. Here are some pointers for effective contributions.

Contributing crates

The process for submitting a new crate or release is currently manual, although automated support through the alr publish command is in the roadmap. The sequence of steps to take is described after some introductory concepts; you can also ask for help in the gitter channel of the project.

General concepts

The community index is a collection of TOML files stored in the alire-index repository, under the index directory. Each file is named after the crate it contains. A crate contains the description of a project, with other metadata, and the list of available releases (identified by their semantic version).

The complete specification of such TOML files is available in this document.

New crates and releases

Contributing a new crate is achieved through a pull-request against the index repository, in which the TOML file for the crate must be provided. Similarly, a new release is published by submitting a pull-request with the necessary modifications to the crate file.

Index branches

The community index is supported through two kinds of branches:

  • stable-x.x.x branches are used by stable versions of alr.
  • devel-x.x.x branches are used to introduce breaking changes in the index format, during the development of alr.

Your alr version knows which branch to use, so you do not need to manually select one. However, when submitting crates/releases as pull requests, you must decide to which branch they will be added: selecting the latest stable branch results in the release becoming immediately available to the latest stable alr. Conversely, using the latest development branch will make the releases available for testing by unstable clients, and will become generally available with the next stable release of alr.

Note that, as of this writing (Dec 2019), only development branches exist, until the first stable release of alr is made.

Checks on contributions

Each crate is "owned" by a list of maintainers, provided with the maintainers-logins property of the crate file. After the initial submission, which will be manually approved (see the POLICY for details), the maintainers of a crate are the only people allowed to submit new releases or metadata modifications to the corresponding crate file.

Detailed steps

These steps describe how to submit a new crate. They are essentially the same for submitting a new release (in the latter case, the existing crate file must be edited instead of created).

  1. Prepare a source archive (zip, tar) with the release sources and project files.
    1. This archive must not contain the alire directory generated by alr in working directories. The alire directory is designed to be put in your VCS ignore list.
    2. The archive must contain a single directory (name not important) containing, in turn, the sources. This is the kind of archives automatically generated by GitHub, GitLab, Sourceforge... or through git archive.
  2. Compute an integrity hash for the archive with alr publish --hash <URL>
    1. The URL can be remote or local (file://), although using the final online file is recommended.
    2. The final online file should be immutable. Note that online autogenerated archives can be found currently in the index, but should be avoided whenever possible (because of lack of immutability guarantees, see this conversation). In the future, alr publish will offer support to generate and upload such files more conveniently.
  3. Fill the crate file providing all the necessary information ([general] section), dependencies (depends-on) and possibly excluded platforms (available). See, for example, the hello world crate, or the empty skeleton template.
  4. Place the crate file in the appropriate directory of your locally checked out index repository, and create a new pull request. The detailed substeps are the usual for submitting contributions in GitHub:
    1. Fork the community index to your GitHub account.
    2. Clone your fork locally and make the changes locally.
    3. Commit and push the changes to your fork.
    4. Create the pull request from your fork against the community repository through the GitHub web interface (or the hub tool).
      1. The base branch you select for the pull request will determine where your changes will become available; see the section on index branches for details.

Once the pull request is verified and merged, the new crate or release will become available for normal use. The open source Ada ecosystem needs all the help it can get, so happy contributing!