This is the shard catalog for https://shardbox.org

This repository contains a list of categories and the shards in each category. For shardbox it provides both a taxonomy and a way to recognize new shards. The shardbox database is regularly synced with the definitions of this catalog.

Contributing

Pull requests against this repo are welcome.

How to add a new shard

You can use this catalog to announce a new shard to shardbox.org.

1. Select which category it should go into (catalog/ folder). If it doesn't fit anywhere else, it should go into Misc.yml.
2. Add an entry into the shards list in the category file. It should be inserted alphabetically, ordered by repository name (that's the last component of the URL). For example github: a/z is sorted after github: z/a. See shard format for details.
3. The description should explain the purpose of the shard in as few words as possible and should be understandable without expert knowledge. Please avoid mentioning that it's a Crystal implementation. All shards in this catalog are Crystal implementations.

How to update a shard's location

When a shard is moved to a different location, its canonical repository needs to be updated. This is for example the case when moving from a user to org namespace on GitHub.

1. Identify the category and respective YAML file where the shard is registered.
2. Add the new canonical repository location. See shard format for details.
3. Move the previous canonical repo to the mirrors section with role: legacy property. This is necessary because existing releases of other shards still reference the old location. Whether its still available at that location or not doesn't matter, but the reference should stay intact.

Guidelines

A shard is eligible to be listed in this catalog if it fits this description:

• Provides some usefulness and reusable features. It doesn't need to be a library or provide a specific API.
• It is meant to be continuously available. There don't need to be any guarantee to be updated or maintained, but it should not simply vanish.
• Written in Crystal.
• Depends only on publicly available dependencies.

If a shard is a dependency of a shard already listed in the catalog, it is automatically discovered by the shardbox database and should be included in the catalog.

A repository referenced in this catalog must be publicly accessible. Mirrors may be non-public or non-accessible; they're still useful for documentation purposes (outdated mirrors should be marked as role: legacy).

Format

The catalog data is contained in the ./catalog folder.

Category

Each category is defined in a .yml file.

Properties:

• name (string, required): Human-readable name of the category.
• slug (string, implicit): Computer-readable name of the category, implict from the file name.
• description (string, optional): Optional description of the category.
• shards (sequence, required): List of shard entries.

Shard

Each shard entry requires exactly one reference to the shard's canonical repository. It is expressed as a mapping from a resolver to an url used for that resolver. For example github: shardbox/shardbox-core. This is the same as defining dependencies in a shard.yml file (see specification). All resolvers supported by shards are supported, except for path (because it is not publicly resolvable by definition).

Properties:

• resolver (one of the following is required):
  • git (string): URL of a git repository (should be publicly available).
  • github (string): Path of a repository on GitHub.
  • gitlab (string): Path of a repository on Gitlab.
  • bitbucket (string): Path of a repository on Bitbucket.
• description (string, optional): Description of the shard.
• mirrors (sequence, optional): A list of mirror repositories.
• state (string, optional):
  • archived: Mark this shard as archived

Mirror

Each mirror entry points to an alternate location for the shard.

Properties:

• resolver (required): Same as for shards
• role (string, optional): Role of this mirror. Possible values:
  • mirror (default): A mirror of the main repository.
  • legacy: A mirror that is no longer available.

The reason for these properties is that the same shard can be available from different sources and other shards can use these different repositories as dependencies (including historical releases). When different repositories reference the same shard, they should show up as one.

Example:

- github: kemalcr/kemal
  description: Lightning Fast, Super Simple web framework. Inspired by Sinatra
  mirrors:
  - github: sdogruyol/kemal
    role: legacy