Deployment and repo updates

[GrantBirki]

This pull request layers all my changes that I made in my own fork into this project.

Most of the changes here is related to me vendoring shards into the lib/ directory. This helps to maintain repeatable builds in CI. Also, I ran crystal docs. Between these two things, it made the PR diff massive so for that I do apologize

This PR also adds support for deployments.cr as well 🚀

[GrantBirki]

@watzon here are all my changes that I layered in. I'm using all these exact changes over in a new project and they are working as expected. That project where this is all working can be found here.

[watzon]

It's generally discouraged to vendor libraries like that. Have you considered tagging a specific commit for each dependency in shard.yml instead?

[GrantBirki]

It's generally discouraged to vendor libraries like that. Have you considered tagging a specific commit for each dependency in shard.yml instead?

I did briefly look into doing that. The issue that I ran into though (this happened to the OSS community many times in the past.. cough nodejs... npm.. cough) is where an upstream repo is fully deleted. So for example, we have runtime dependency on halite. If the icyleaf/halite repo is suddenly deleted, we have no realistic way of building this project unless we do one of the following:

• Maintain a fork of that project
• Vendor the entire project by committing the lib/ directory

This is a highly opinionated dependency management approach and its something a lot of folks in the Ruby community follow religiously. Its also something that I try my best to follow as well because of the whole who owns your availability... you... concept.

I have also been chatting quite a bit with some of the maintainers of crystal about the best way to vendor shards and they did suggest doing exactly this as the "best way" to vendor shards in crystal's current state.

That being said, if you don't think vendoring shards in the lib/ dir is something you want to do, I can certainly remove it. I think it does add a fair bit of value here though as its protects the project from upstream issues.

Let me know what you think!

[watzon]

Gotcha. I'm not wholly opposed to it, but it definitely makes commits like this harder to parse. It might be worth looking into removing halite as a dependency entirely, since it's actually quite a bit slower than the built in HTTP client. When I added it I did so just because I liked halite's API, but I ended up having issues with it in another project so I haven't been using it anymore.

Another option outside of vendoring, and something I tend to do myself more often would be to just fork the projects into this org and reference that fork in shard.yml. For now I'll go ahead and merge this though, and that's something we can look at in the future.