cheshire
/
hscloud
forked from hswaw/hscloud
1
0
Fork 0
Code Pull Requests Activity

doc/codelabs: add getting-started/checking-out 

Change-Id: I64d6be74194a902601fd2ff6121b7232353ec8ed
master
q3k 2021-03-21 13:55:24 +01:00
parent 162fcc328d
commit 2fd9019f15
4 changed files with 127 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -2,14 +2,6 @@
`hscloud` is the main monorepo of the Warsaw Hackerspace infrastructure code.
Any time you see a `//path/like/this`, it refers to the root of hscloud, ie. the path `path/like/this` in this repository. Perforce and/or Bazel users should feel right at home.
Viewing this documentation
--------------------------
For a pleaseant web viewing experience, [see this documentation in hackdoc](https://hackdoc.hackerspace.pl/). This will allow you to read this markdown file (and others) in a pretty, linkable view.
Getting started
---------------

110
doc/codelabs/getting-started/checking-out.md Normal file
View File

@ -0,0 +1,110 @@
Checking out hscloud
====================
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.
[TOC]
Background
----------
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.
What do I use it for?
---------------------
If you've been pointed towards hscloud, it's probably due to one of the below reasons:
- You want to deploy something for the Hackerspace
- You want to fix/patch some software already running
- You want to run some of your personal projects on our compute cluster
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!
What is hackdoc?
----------------
If you're viewing this on [https://hackdoc.hackerspace.pl/doc/codelabs/getting-started/checking-out.md](https://hackdoc.hackerspace.pl/doc/codelabs/getting-started/checking-out.md) - you're using [Hackdoc](/devtools/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](https://cs.hackerspace.pl/hscloud) or [gerrit.hackerspace.pl, our code review tool](https://gerrit.hackerspace.pl). 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.
Local requirements & Git clone
==============================
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.
Code organization
-----------------
**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:
- There is only a single branch we work on: `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.
- There are no personal branches. Instead, if you want to commit some stuff for personal/experimental use, just drop it into a `//personal/$your-username`, and you will be able to land things there without review.
- There is a single repository. All projects and code lives within hscloud. This allows you to make a single change that alters, for examplle, client and server side code of an application simultaneously, without having to coordinate this change across multiple repositories.
What's up with `//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 diredctory foo inside hscloud.
What are changes?
-----------------
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](https://gerrit.hackerspace.pl). Each change can be identified by:
- The git commit hash when it got merged into `master` (eg. `146c99e58e46f3c026e170794326521de6bf13e1`)
- The ChangeId hash within the git commit message (eg. `I8b64103cb87d8b185ff35165695a18cb19fea523`)
- The Change number on gerrit (eg. [https://gerrit.hackerspace.pl/841](https://gerrit.hackerspace.pl/841))
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.
Viewing hscloud online
----------------------
We have a **code search** tool/web interface available on [https://cs.hackerspace.pl/hscloud](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.
So what's in hscloud? Where do I start?
---------------------------------------
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](/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!
Where do we report and track issues?
------------------------------------
We have an issue tracker at [https://issues.hackerspae.pl/](https://issues.hackerspace.pl/). It's a Redmine instance so it's not super friendly, so we made some shorthand links:
- [https://b.hswaw.net](https://b.hswaw.net) will take you to a page with you personal dashboard.
- [https://b.hswaw.net/123](https://b.hswaw.net/123) will take you to issue number 123.
- [https://b.hswaw.net/new](https://b.hswaw.net/new) will take you to a page to file a new issue.
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 :).
Further steps
=============
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:
- [Your first hscloud Change](your-first-change.md) will guide you through using Gerrit to send your first contribution to hscloud - a small file change in your personal directory.
- **TODO** will guide you through building some code using Bazel, and then writing a tiny bit of Go code of your own.
- **TODO** will guide you through accessing our production Kubernetes cluster and running some code on it.

34
doc/codelabs/getting-started/your-first-change.md
View File

@ -8,9 +8,7 @@ This codelab will teach you how to send your first change to hscloud. We'll be m
Prerequisites
-------------
hscloud is a git repository. If you're new to git, this might be slightly confusing to you, but you should still be able to follow along. In case you need brush up on that, links to relevant resources await you at the bottom of this document.
As for software, you'll need to have git installed on your workstation.
**Required**: [Checking out hscloud](checking-out.md) to understand the basics of the hscloud code structure.
Gerrit concepts
---------------
@ -65,10 +63,19 @@ You should now be able to SSH into Gerrit. As Git access is also over SSH, this
Note that you should be using your Warsaw Hackerspace SSO user name. If that's different from your local workstation username, you'll have to specify `user@gerrit.hackerspace.pl` in all the following commands.
Cloning hscloud and looking around
----------------------------------
Connecting your hscloud checkout to Gerrit
------------------------------------------
Now, clone hscloud and take a look around:
If you've come here from the [Checking out hscloud](checking-out.md) codelab, you probably already have a read-only hscloud checkout over HTTPS. If so, you will have to switch its remote to access Gerrit through your SSH key:
$ cd hscloud
$ git remote remove origin
$ # If your local username is the same as your SSO username:
$ git remote origin add gerrit.hackerspace.pl:hscloud
# # Otherwise, you'll have to specify your SSO username explicitly:
$ git remote origin add user@gerrit.hackerspace.pl:hscloud
Or, **if you don't have a hscloud checkout on hand**, just clone it from scratch using the authenticated Gerrit endpoint:
$ git clone gerrit.hackerspace.pl:hscloud
Cloning into 'hscloud'...
@ -78,20 +85,11 @@ Now, clone hscloud and take a look around:
Receiving objects: 100% (5469/5469), 15.25 MiB | 14.08 MiB/s, done.
Resolving deltas: 100% (2686/2686), done.
$ cd hscloud
$ ls
app bgpwtf BUILD bzl cluster COPYING dc devtools doc env.fish env.sh gcp go hackdoc.toml hswaw kube OWNERS personal README.md third_party tools WORKSPACE
$
If you've already cloned hscloud before (eg. over https), either clone it again or update your origin to point at `user@gerrit.hackerspace.pl:hscloud`.
You can also use Gitiles (a part of Gerrit) to view hscloud in your web browser: https://gerrit.hackerspace.pl/plugins/gitiles/hscloud/+/refs/heads/master
Any time you see a `//path/written/like/this`, `//` refers to the root of the hscloud checkout. For example, `//devtools/gerrit` contains all code related to our Gerrit instance. If you want to learn more about hscloud's directory structure, start at [//README.md](/README.md).
Configuring git for Gerrit
--------------------------
There's just a bit more of one-time setup that you'll need to do in order to send changes to Gerrit:
You now have hscloud cloned from an authenticated Gerrit endpoint. Gerrit knows it's you trying to access (and/or write) code. However, there's just a bit more of one-time setup that you'll need to do in order to send changes to Gerrit:
$ git config user.email 'user@hackerspace.pl' # replace user with your SSO login name
$ curl -Lo .git/hooks/commit-msg https://gerrit.hackerspace.pl/tools/hooks/commit-msg
@ -190,6 +188,6 @@ Further steps
-------------
- If you need a **Git refresher** - we highly recommend the [Git Visual Reference](https://marklodato.github.io/visual-git-guide/index-en.html)
- While this codelab showed you how to create and submit CRs, you didn't see anything about code review. Watch this space for a codelab about that.
- You should now be able to commit and change code. Watch this space for a link to a codelab on using Bazel or writing a simple microservice in Go.
- **TODO** will guide you through building some code using Bazel, and then writing a tiny bit of Go code of your own.
- **TODO** will guide you through accessing our production Kubernetes cluster and running some code on it.

1
doc/codelabs/index.md
View File

@ -8,4 +8,5 @@ Yes, there aren't many of these yet. Wanna change that? :)
Getting started
---------------
- [**Checking out hscloud**](getting-started/checking-out.md) - how to get a copy of hscloud, how to navigate around it, and what's what. This is nearly **mandatory** for anyone who wishes to interact with hscloud.
- [**Your First Change**](getting-started/your-first-change.md) - how to use Gerrit and git to send your first change to hscloud, and an intro to personal directories. Using Gerrit can be somewhat confusing even (or especially) if you're used to Gitflow or GitHub.