This codelab will introduce you to the basics of working with hscloud - including what it it, how to use it, and what next steps can you take afterwards. It's strongly recommended for everyone who wants to interact with hscloud, k0, or any of the 'new style' Warsaw Hackerspace infrastructure.
By the end, you'll have a hscloud checkout and general understanding of what's where and what tools are available to interact with hscloud.
Welcome to hscloud! This is a repository of code and set of infrastructure born around the Warsaw Hackerspace. It started off as a monorepo for infrastructure-as-code for a set of cloud-like infrastructure at the hackerspace, but has since grown to accumulate a bunch of semi-related code: everything from Nix machine definitions to game servers.
If you've been pointed towards hscloud, it's probably due to one of the below reasons:
All of these are first-class functionality within hscloud, and they should be as straightforward to use as possible. If anything doesn't make immediate sense, or you are confused by something that seems unclear - contact q3k and he will make sure to help you out and update the documentation so that the next person doesn't have this issue.
This documentation, by the way, is also kept within hscloud!
If you're viewing this on https://hackdoc.hackerspace.pl/doc/codelabs/getting-started/checking-out.md - you're using Hackdoc! Hackdoc renders some of the code within hscloud as more prose-oriented documentation, like these codelabs. Somewhere on the right hand side of this page you should be able to click a View Source button to see what document this was rendered from.
You could instead also be reading this from cs.hackerspace.pl, our code browser view or gerrit.hackerspace.pl, our code review tool. Both of these will show you the same content as the hackdoc view, but less richly rendered and linked. We highly recommend viewing this via Hackdoc as linked above for the best possible experience.
First, you need to make a local clone of hscloud on your development machine - ie., the computer/laptop you want to work on. We support generic glibc-based Linux distributions (eg. Ubuntu, Debian, Fedora), NixOS and to a certain degree, macOS.
Unless you're running something different from the above, we highly recommend not working on hscloud from within a container or VM, as our build system already takes care of hermetic builds and reproducibility - and containers/VMs will only get in the way.
Once you've found a machine and cd'd to a directory where you want to clone hscloud, do the following:
$ git clone https://gerrit.hackerspace.pl/hscloud.git [...] $ cd hscloud $ head -n 4 doc/codelabs/getting-started/checking-out.md
and you should see the source for this document, proving that you've succesfully gotten hold of a copy of hscloud.
hscloud is a branchless monorepo. If you've never worked with such a setup before, you might find it slightly odd and coutnerintuitive. Here's what we mean by branchless monorepo:
master. Any time you want to introduce a change to hscloud, you always start off master at the newest possible HEAD, add some changes on top, and then get these reviewed and merged. We do not do feature branches, release trains, or release versions.//personal/$your-username, and you will be able to land things there without review.//these/paths?These paths, sometimes called depot paths, are a convention to refer to paths within hscloud. For example, //foo/bar means a file or directory named bar within a directory named foo in the root of the hscloud repository.
These paths are notably used by Bazel, our build system, which extends the syntax slightly: //foo/bar:baz means a file or build target named baz within a directory bar within a directory foo inside hscloud.
Changes, or Change Requests, or Change Lists (all used interchangably) are modifications to the hscloud repository. Each change corresponds to a single Git commit that has been reviewed on gerrit, our code review tool. Each change can be identified by:
master (eg. 146c99e58e46f3c026e170794326521de6bf13e1)I8b64103cb87d8b185ff35165695a18cb19fea523)Going from Change number to git commit hash or ChangeId is easy - gerrit will show these to you when you visit the page for any given Change number. Going the otherway is currently not super intuitive - you have to use Gerrit's web interface to search for either git commit hash or ChangeId.
We have a code search tool/web interface available on https://cs.hackerspace.pl/hscloud, which is probably the most convenient way to browse hscloud online, and link it to others. Gerrit also has its own built-in code viewer (Gitiles), but its use is being phased out.
If you want to modify something, you'll first have to figure out where is it in hscloud. For that, either use codesearch, or ask any of the people who work on hscloud for guidance. There is also a somewhat up-to-date directory of interesting top-level things at //README.md.
Once you have that, look at other codelabs for guidance on working with specific technologies within hscloud. If something's missing - ask someone knowledgeable to either document it, or help you document it!
We have an issue tracker at https://issues.hackerspace.pl/. It's a Redmine instance so it's not super friendly, so we made some shorthand links:
File issues often, file issues early, ask for forgiveness later! It's much easier to keep track of things on there than to chat up people. Don't worry about categorizing, and feel free to assign q3k for anything.
You can naturally also ask on #members:hackerspace.pl or even #general:hackerspace.pl - but if you encounter an problem, we highly recommend filing issues instead of chatting people up :).
Now that you have a local hscloud checkout and mostly know why it exists and how it's laid out, there's a few next steps you can take: