Hosting on GitLab

    • Create a GitLab project with the same and description as specified in your shard.yml.

    • Push it:

      1. $ git push origin master

    Next, let’s setup a GitLab Pipeline that can run our tests and build/deploy the docs when we push code to the repo.

    Simply, you can just add the following file to the root of the repo and name it .gitlab-ci.yml

    This creates two jobs. The first one is titled “spec & format” (you can use any name you like) and by default goes in the “test” stage of the pipeline. It just runs the array of commands in script on a brand new instance of the docker container specified by image. You’ll probably want to lock that container to the version of crystal you’re using (the one specified in your shard.yml) but for this example we’ll just use the latest tag.

    The test stage of the pipeline will either pass (each element of the array returned a healthy exit code) or it will fail (one of the elements returned an error).

    If it passes, then the pipeline will move onto the second job we defined here which “pages”. This is a special job just for deploying content to your gitlab pages site! This one is executed after tests have passed because we specified that it should occur in the “deploy” stage. It again runs the commands in script (this time building the docs), but this time we tell it to preserve the path (where we stashed the docs) as an artifact of the job.

    The before_script and cache keys in the file are for running the same script in every job (shards install) and for hanging onto the files that were created (cache). They’re not necessary if your shard doesn’t have any dependencies.

    If you commit the above file to your project and push, you’ll trigger your first run of the new pipeline.

    1. $ git add -A && git commit -am 'Add .gitlab-ci.yml' && git push origin master

    While that pipeline is running, let’s attach some badges to the project to show off our docs and the (hopefully) successful state of our pipeline. (You might want to read the badges docs.)

    A badge is just a link with an image. So let’s create a link to our pipeline and fetch a badge image from the .

    In the Badges section of the General settings, we’ll first add a release badge. The link is: https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/pipelines and the Badge Image URL is: https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/badges/master/pipeline.svg.

    And now if the pipleline has finished we’ll have docs and we can link to them with a generic badge from .

    • Link: https://<YOUR-GITLAB-USERNAME>.gitlab.io/<YOUR-REPOSITORY-NAME>
    • Image: https://img.shields.io/badge/docs-available-brightgreen.svg

    Releases

    A release is just a special commit in your history with a name (see ).

    According to the Crystal Shards README,

    As you’ll see from the , you can either create an annotated tag along with release notes/files in the UI:

    or you can create the tag from the command line like so:

    push it up

    1. $ git push origin master --follow-tags

    and then use the UI to add/edit the release note and attach files.

    Best Practices

    If you’d like you can also add a shields.io badge for the release. GitLab doesn’t have full support for this kind of thing, and until someone adds a to shields.io, we’ll have to just code in the version number in the URLs directly.

    • Link: https://img.shields.io/badge/release-<VERSION>-brightgreen.svg
    • Image: https://img.shields.io/badge/release-<VERSION>-brightgreen.svg

    where <VERSION> is the version number prefixed with a v like this: v0.1.0.

    At the moment, crystalshards.xyz only uses the GitHub API, so if you want your library to be indexed on that service you can set up a “push mirror” from GitLab to GitHub.

    1. Create a GitHub repository with the same name as your project.
    2. Follow the instructions here: https://docs.gitlab.com/ee/workflow/repository_mirroring.html#setting-up-a-push-mirror-from-gitlab-to-github-core
    3. Edit your GitHub description. The first few words of this description will show up in the search results of but not the whole string, so for example, you could use the following
      • Description: Words that are the same forwards and backwards. This is a mirror of: