crystal-shards-101 v0.1.0
💎 👩🏫 Crystal Shards 101
How to write and release Crystal Shards.
What's a Shard?
Simply put, a Shard is a package of Crystal code, made to be shared-with and used-by other projects.
Installation
If you haven't already, install the latest version of the Crystal compiler. Installation instructions here
Usage
In this tutorial, we'll be making a Crystal library called palindrome-example.
For those who don't know, a palindrome is a word which is spelled the same way forwards as it is backwards. e.g. racecar, mom, dad, kayak, madam
Creating the Project
Begin by using the Crystal compiler to generate a new library in a subfolder of the current directory.
In your terminal, enter:
$ crystal init lib palindrome-example
create palindrome-example/.gitignore
create palindrome-example/.editorconfig
create palindrome-example/LICENSE
create palindrome-example/README.md
create palindrome-example/.travis.yml
create palindrome-example/shard.yml
create palindrome-example/src/palindrome-example.cr
create palindrome-example/src/palindrome-example/version.cr
create palindrome-example/spec/spec_helper.cr
create palindrome-example/spec/palindrome-example_spec.cr
Initialized empty Git repository in /Users/YOUR_USER_NAME/.../palindrome-example/.git/
...and cd
into the directory:
cd palindrome-example
Then add
& commit
to start tracking the files with Git:
$ git add -A
$ git commit -am "First Commit"
[master (root-commit) 77bad84] First Commit
10 files changed, 102 insertions(+)
create mode 100644 .editorconfig
create mode 100644 .gitignore
create mode 100644 .travis.yml
create mode 100644 LICENSE
create mode 100644 README.md
create mode 100644 shard.yml
create mode 100644 spec/palindrome-example_spec.cr
create mode 100644 spec/spec_helper.cr
create mode 100644 src/palindrome-example.cr
create mode 100644 src/palindrome-example/version.cr
Writing the Code
The code you write is up to you, but how you write it impacts whether people want to use your library and/or help you maintain it.
TDD
- Test your code. All of it. It's the only way for anyone, including you, to know if it works.
- Crystal has an awesome built-in testing library. Use it!
Documentation
- Document your code with comments. All of it. Even the private methods.
- Crystal has an awesome built-in documentation generator. Use it!
Run crystal doc
and open the files in /doc/
in your browser to see how your documentation is looking along the way. (the process of seeing your comments and code magically turned into documentation is surprisingly satisfying)
Coding Style
- It's fine to have your own style, but sticking to some core rubrics defined by the Crystal team can help keep your code consistent, readable and usable for other developers.
Writing a README
A good README can make or break your project. Awesome README is a nice curation of examples and resources on the topic.
Most importantly, your README should explain:
- what your library is
- what it does
- how to use it
This explanation should include a few examples along with subheadings.
NOTE: Be sure to replace all instances of [your-github-name]
in the Crystal-generated README template with your Github username.
Fill out and insert the following block of markdown build badges below the description in your README.
The purpose of this is to inform users on the status of certain aspects of your repository. More on this in a minute.
[![Build Status](https://travis-ci.org/[YOUR-GITHUB-USERNAME]/[YOUR-REPOSITORY-NAME].svg?branch=master)](https://travis-ci.org/[YOUR-GITHUB-USERNAME]/[YOUR-REPOSITORY-NAME]) [![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://[YOUR-GITHUB-USERNAME].github.io/[YOUR-REPOSITORY-NAME]/) [![GitHub release](https://img.shields.io/github/release/[YOUR-GITHUB-USERNAME]/[YOUR-REPOSITORY-NAME].svg)](https://github.com/[YOUR-GITHUB-USERNAME]/[YOUR-REPOSITORY-NAME]/releases)
Writing a shard.yml
The spec is your rulebook. Follow it.
Name
Your shard.yml
's name
property should be concise and descriptive.
- Search crystalshards.xyz to check if your name is already taken.
e.g.
name: palindrome-example
Description
Add a description
to your shard.yml
.
A description
is a single line description used to search for and find your shard.
A description should be:
- Informative
- Discoverable
Optimizing
It's hard for anyone to use your project if they can't find it. crystalshards.xyz is currently the go-to place for Crystal libraries, so that's what we'll optimize for.
There are people looking for the exact functionality of our library and the general functionality of our library. e.g. Bob needs a palindrome library, but Felipe is just looking for libraries involving text and Susan is looking for libraries involving spelling.
Our name
is already descriptive enough for Bob's search of "palindrome". We don't need to repeat the palindrome keyword. Instead, we'll catch Susan's search for "spelling" and Felipe's search for "text".
description: |
A textual algorithm to tell if a word is spelled the same way forwards as it is backwards.
Github
-
Create a repository with the same
name
anddescription
as specified in yourshard.yml
. -
Add and commit everything:
$ git add -A && git commit -am "shard complete"
- Add the remote:
$ git remote add public https://github.com/[YOUR-GITHUB-NAME]/[YOUR-REPOSITORY-NAME].git
- Push it:
$ git push public master
Github Releases
It's good practice to do Github Releases.
Start by navigating to your repository's releases page.
- This can be found at https://github.com/YOUR-GITHUB-NAME/YOUR-REPOSITORY-NAME/releases
Click "Create a new release".
According to the Crystal Shards README,
When libraries are installed from Git repositories, the repository is expected to have version tags following a semver-like format, prefixed with a
v
. Examples: v1.2.3, v2.0.0-rc1 or v2017.04.1
Accordingly, in the input that says tag version
, type v0.1.0
. Make sure this matches the version
in shard.yml
. Title it v0.1.0
and write a short description for the release.
Click "Publish release" and you're done!
You'll now notice that the Github Release badge has updated in your README.
Follow Semantic Versioning and create a new release every time your push to master
.
Setting up Travis CI and .travis.yml
If you haven't already, sign up for Travis CI.
Add the following lines to your .travis.yml
:
script:
- crystal spec
This tells Travis CI to run your tests.
Commit and push to Github.
Follow these guidelines to get your repo up & running on Travis CI.
Once you're up and running, and the build is passing, the Build badge will update in your README.
Hosting your docs
on Github-Pages
Add the following script
to your .travis.yml
:
- crystal docs
This tells Travis CI to generate your documentation.
Next, add the following lines to your .travis.yml
.
deploy:
provider: pages
skip_cleanup: true
github_token: $GITHUB_TOKEN
project_name: YOUR-GITHUB-REPOSITORY-NAME
on:
branch: master
local_dir: doc
Set the Environment Variable, GITHUB_TOKEN
, with your personal access token.
If you've been following along, your .travis.yml
file should look something like this:
language: crystal
script:
- crystal spec
- crystal docs
deploy:
provider: pages
skip_cleanup: true
github_token: $GITHUB_TOKEN
project_name: YOUR-GITHUB-REPOSITORY-NAME
on:
branch: master
local_dir: doc
Click Here for the official documentation on deploying to GH-Pages with Travis CI.
Contributing
- Fork it ( https://github.com/mccallofthewild/crystal-shards-101/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
Contributors
- McCall Alexander mccallofthewild - creator, maintainer
crystal-shards-101
- 4
- 0
- 0
- 0
- 0
- about 7 years ago
- October 11, 2017
MIT License
Sat, 21 Dec 2024 18:44:24 GMT