{"id":15713714,"url":"https://github.com/mccallofthewild/crystal-shards-101","last_synced_at":"2025-03-30T18:47:11.674Z","repository":{"id":143921613,"uuid":"106592190","full_name":"mccallofthewild/crystal-shards-101","owner":"mccallofthewild","description":"A How-To Guide and Checklist for Releasing Crystal Shards","archived":false,"fork":false,"pushed_at":"2017-10-11T22:54:43.000Z","size":15,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-05T21:27:01.849Z","etag":null,"topics":["crystal","crystal-language","crystal-shards","crystallang","shards"],"latest_commit_sha":null,"homepage":"https://mccallofthewild.github.io/crystal-shards-101","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mccallofthewild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-11T18:18:13.000Z","updated_at":"2018-04-10T11:10:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"94c4d1e5-4286-4af4-a1a3-764862688983","html_url":"https://github.com/mccallofthewild/crystal-shards-101","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccallofthewild%2Fcrystal-shards-101","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccallofthewild%2Fcrystal-shards-101/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccallofthewild%2Fcrystal-shards-101/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccallofthewild%2Fcrystal-shards-101/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mccallofthewild","download_url":"https://codeload.github.com/mccallofthewild/crystal-shards-101/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246365640,"owners_count":20765546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal","crystal-language","crystal-shards","crystallang","shards"],"created_at":"2024-10-03T21:33:03.727Z","updated_at":"2025-03-30T18:47:11.466Z","avatar_url":"https://github.com/mccallofthewild.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💎 👩‍🏫 Crystal Shards 101\n\nHow to write and release Crystal Shards.\n\n##\n\n [![Build Status](https://travis-ci.org/mccallofthewild/crystal-shards-101.svg?branch=master)](https://travis-ci.org/mccallofthewild/crystal-shards-101) [![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://mccallofthewild.github.io/crystal-shards-101/) [![GitHub release](https://img.shields.io/github/release/mccallofthewild/crystal-shards-101.svg)](https://github.com/mccallofthewild/crystal-shards-101/releases)\n\n## _What's a Shard?_\nSimply put, a Shard is a package of Crystal code, made to be shared-with and used-by other projects.\n\n## Installation\n\nIf you haven't already, install the latest version of the Crystal compiler.\n[Installation instructions here](https://crystal-lang.org/docs/installation/)\n\n\n## Usage\n\nIn this tutorial, we'll be making a Crystal library called _palindrome-example_.\n\n\u003e 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\n\n### Creating the Project\nBegin by using [the Crystal compiler](https://crystal-lang.org/docs/using_the_compiler/) to generate a new library in a subfolder of the current directory.\n\nIn your terminal, enter:\n\n```bash\n $  crystal init lib palindrome-example\n      create  palindrome-example/.gitignore\n      create  palindrome-example/.editorconfig\n      create  palindrome-example/LICENSE\n      create  palindrome-example/README.md\n      create  palindrome-example/.travis.yml\n      create  palindrome-example/shard.yml\n      create  palindrome-example/src/palindrome-example.cr\n      create  palindrome-example/src/palindrome-example/version.cr\n      create  palindrome-example/spec/spec_helper.cr\n      create  palindrome-example/spec/palindrome-example_spec.cr\nInitialized empty Git repository in /Users/YOUR_USER_NAME/.../palindrome-example/.git/\n```\n\n...and `cd` into the directory:\n\n```bash\ncd palindrome-example\n```\n\nThen `add` \u0026 `commit` to start tracking the files with Git:\n\n```bash\n $  git add -A\n $  git commit -am \"First Commit\"\n[master (root-commit) 77bad84] First Commit\n 10 files changed, 102 insertions(+)\n create mode 100644 .editorconfig\n create mode 100644 .gitignore\n create mode 100644 .travis.yml\n create mode 100644 LICENSE\n create mode 100644 README.md\n create mode 100644 shard.yml\n create mode 100644 spec/palindrome-example_spec.cr\n create mode 100644 spec/spec_helper.cr\n create mode 100644 src/palindrome-example.cr\n create mode 100644 src/palindrome-example/version.cr\n```\n\n### Writing the Code\n\nThe 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.\n\n#### TDD\n- Test your code. All of it. It's the only way for anyone, including you, to know if it works.\n- Crystal has [an awesome built-in testing library](https://crystal-lang.org/api/0.23.1/Spec.html). Use it!\n\n#### Documentation\n- Document your code with comments. All of it. Even the private methods.\n- Crystal has [an awesome built-in documentation generator](https://crystal-lang.org/docs/conventions/documenting_code.html). Use it!\n\nRun `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)\n\n#### Coding Style \n- It's fine to have your own style, but sticking to [some core rubrics defined by the Crystal team](https://crystal-lang.org/docs/conventions/coding_style.html) can help keep your code consistent, readable and usable for other developers.\n\n\n### Writing a README\n\nA good README can make or break your project.\n[Awesome README](https://github.com/matiassingers/awesome-readme) is a nice curation of examples and resources on the topic.\n\nMost importantly, your README should explain: \n1. what your library is \n2. what it does\n3. how to use it\n\nThis explanation should include a few examples along with subheadings.\n\nNOTE: Be sure to replace all instances of `[your-github-name]` in the Crystal-generated README template with your Github username.\n\nFill out and insert the following block of markdown build badges below the description in your README. \n\u003e The purpose of this is to inform users on the status of certain aspects of your repository. More on this in a minute.\n```Markdown\n[![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)\n```\n\n\n### Writing a `shard.yml`\n\n[The spec](https://github.com/crystal-lang/shards/blob/master/SPEC.md#names) is your rulebook. Follow it.\n\n#### Name\nYour `shard.yml`'s `name` property should be concise and descriptive. \n\n- Search [crystalshards.xyz](https://crystalshards.xyz/) to check if your name is already taken.\n\ne.g.\n```YAML\nname: palindrome-example\n```\n\n#### Description\nAdd a `description` to your `shard.yml`. \n\nA `description` is a single line description used to search for and find your shard.\n\nA description should be:\n1. Informative\n2. Discoverable\n\n#### Optimizing\nIt's hard for anyone to use your project if they can't find it.\n[crystalshards.xyz](https://crystalshards.xyz/) is currently the go-to place for Crystal libraries, so that's what we'll optimize for.\n\nThere are people looking for the _exact_ functionality of our library and the _general_ functionality of our library.\ne.g. Bob needs a palindrome library, but Felipe is just looking for libraries involving text and Susan is looking for libraries involving spelling.\n\nOur `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\".\n```YAML\ndescription: |\n  A textual algorithm to tell if a word is spelled the same way forwards as it is backwards.\n```\n\n### Github\n\n- Create a repository with the same `name` and `description` as specified in your `shard.yml`.\n\n- Add and commit everything:\n```bash\n$ git add -A \u0026\u0026 git commit -am \"shard complete\"\n```\n- Add the remote: \n```bash \n$ git remote add public https://github.com/[YOUR-GITHUB-NAME]/[YOUR-REPOSITORY-NAME].git\n```\n- Push it: \n```bash\n$ git push public master\n```\n\n#### Github Releases\nIt's good practice to do Github Releases. \n\nStart by navigating to your repository's _releases_ page.\n  - This can be found at _https://github.com/YOUR-GITHUB-NAME/YOUR-REPOSITORY-NAME/releases_\n\nClick \"Create a new release\".\n\nAccording to [the Crystal Shards README](https://github.com/crystal-lang/shards/blob/master/README.md), \n\u003e 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\n\nAccordingly, 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.\n\nClick \"Publish release\" and you're done!\n\nYou'll now notice that the Github Release badge has updated in your README.\n\nFollow [Semantic Versioning](http://semver.org/) and create a new release every time your push to `master`.\n\n### Setting up Travis CI and `.travis.yml`\nIf you haven't already, [sign up for Travis CI](https://travis-ci.org/).\n\nAdd the following lines to your `.travis.yml`:\n```YAML\nscript:\n  - crystal spec\n```\nThis tells Travis CI to run your tests.\n\nCommit and push to Github.\n\nFollow [these guidelines](https://docs.travis-ci.com/user/getting-started/) to get your repo up \u0026 running on Travis CI.\n\nOnce you're up and running, and the build is passing, the Build badge will update in your README.\n\n\n### Hosting your `docs` on Github-Pages\n\nAdd the following `script` to your `.travis.yml`:\n```YAML\n  - crystal docs\n```\n\nThis tells Travis CI to generate your documentation.\n\nNext, add the following lines to your `.travis.yml`.\n\n```YAML\ndeploy:\n  provider: pages\n  skip_cleanup: true\n  github_token: $GITHUB_TOKEN\n  project_name: YOUR-GITHUB-REPOSITORY-NAME\n  on:\n    branch: master\n  local_dir: doc\n```\n\n[Set the Environment Variable](https://docs.travis-ci.com/user/environment-variables#Defining-Variables-in-Repository-Settings), `GITHUB_TOKEN`, with your [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).\n\nIf you've been following along, your `.travis.yml` file should look something like this:\n\n```YAML\nlanguage: crystal\nscript:\n  - crystal spec\n  - crystal docs\ndeploy:\n  provider: pages\n  skip_cleanup: true\n  github_token: $GITHUB_TOKEN\n  project_name: YOUR-GITHUB-REPOSITORY-NAME\n  on:\n    branch: master\n  local_dir: doc\n```\n\n[Click Here](https://docs.travis-ci.com/user/deployment/pages/) for the official documentation on deploying to GH-Pages with Travis CI.\n\n\n## Contributing\n\n1. Fork it ( https://github.com/mccallofthewild/crystal-shards-101/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [McCall Alexander](https://github.com/mccallofthewild) mccallofthewild - creator, maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmccallofthewild%2Fcrystal-shards-101","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmccallofthewild%2Fcrystal-shards-101","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmccallofthewild%2Fcrystal-shards-101/lists"}