From b5db94cfe1f70a87dcf68cb35fb2fb3aab729f0c Mon Sep 17 00:00:00 2001 From: Alejandro R Mosteo Date: Tue, 6 Apr 2021 11:09:02 +0200 Subject: [PATCH] Updated documentation (readme, contributing) (#269) --- CONTRIBUTING.md | 65 ++++++------------------------------------------- README.md | 24 ++++++------------ 2 files changed, 14 insertions(+), 75 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27cb5e34..6984c868 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,61 +1,10 @@ -Thanks for your interest in the Alire project. Here are some pointers for effective contributions. +Thanks for your interest in the Alire project. Please find more information at +one of these sources: -# Contributing crates +- Main repository (development version): https://github.com/alire-project/alire +- Website (stable release information): https://alire.ada.dev +- Live discussion: https://gitter.im/ada-lang/Alire -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](https://gitter.im/ada-lang/Alire) of the project. +Concretely, the documentation about submission of releases is found at -## General concepts - -The community index is a collection of [TOML](https://github.com/toml-lang/toml) -files stored in the [alire-index](https://github.com/alire-project/alire-index) repository, -under the [index](https://github.com/alire-project/alire-index/blob/master/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](https://semver.org/)). - -The complete specification of such TOML files is available in this [document](https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md). - -## 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](https://github.com/alire-project/alire-index/blob/master/POLICY.md) 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. - 1. 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`. -1. Compute an integrity hash for the archive with `alr publish --hash ` - 1. The URL can be remote or local (`file://`), although using the final online file is recommended. - 1. 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](https://github.community/t5/How-to-use-Git-and-GitHub/Ensuring-identical-tarballs-from-releases/m-p/34196/highlight/true#M8997)). In the future, `alr publish` will offer support to generate and upload such files more conveniently. -1. 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](https://github.com/alire-project/alire-index/blob/master/index/he/hello.toml) crate, or the [empty skeleton](https://github.com/alire-project/alire-index/blob/master/templates/skeleton.toml) template. -1. 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. - 1. Clone your fork locally and make the changes locally. - 1. Commit and push the changes to your fork. - 1. Create the pull request from your fork against the community repository through the GitHub web interface (or the [`hub`](https://github.com/github/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! +- https://alire.ada.dev/docs/#publishing-your-projects-in-alire diff --git a/README.md b/README.md index 84f82bba..7d904774 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,13 @@ -# Alire Catalog +# Alire Community Index [![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/ada-lang/Alire) -This repository hosts the official community-maintained index of Ada projects -to be used with the `alr` tool. Please visit -https://github.com/alire-project/alire to download `alr`. +This repository hosts the official community-maintained index to be used with the `alr` tool. -## Contributing crates to the index +Please visit https://github.com/alire-project/alire to download `alr`. -Please check the information in the [CONTRIBUTING.md](CONTRIBUTING.md) file. +Please open a pull request to submit a new release (read +further [here](https://alire.ada.dev/docs/#publishing-your-projects-in-alire) +about it). -## TODO - -Here are sources of projects that might be interesting to add to this index: - -* [awesome-ada](https://github.com/ohenley/awesome-ada) (Top notch!) -* [GitHub projects, sorted by star - count](https://github.com/search?o=desc&l=Ada&q=ada&s=stars&type=Repositories) -* [AdaIC's Free Tools and - Libraries](http://www.adaic.org/ada-resources/tools-libraries/) -* [Libraries in the Ada Programming - WikiBook](https://en.wikibooks.org/wiki/Ada_Programming/Libraries) +To report an issue, open it at https://github.com/alire-project/alire/issues