diff options
| -rw-r--r-- | .gitignore | 3 | ||||
| -rw-r--r-- | .templates/base.html | 66 | ||||
| -rw-r--r-- | .templates/document.html | 12 | ||||
| -rw-r--r-- | .templates/listing.html | 44 | ||||
| -rw-r--r-- | README.md | 15 | ||||
| -rw-r--r-- | archetypes/default.md | 5 | ||||
| -rw-r--r-- | content/_index.md | 9 | ||||
| -rw-r--r-- | content/code/_index.md | 7 | ||||
| -rw-r--r-- | content/code/commit-messages.md (renamed from docs/code/commit-messages.md) | 9 | ||||
| -rw-r--r-- | content/code/configuring-browser-apps.md (renamed from docs/code/configuring-browser-apps.md) | 9 | ||||
| -rw-r--r-- | content/code/tools-convention.md (renamed from docs/code/tools-convention.md) | 60 | ||||
| -rw-r--r-- | content/code/users-rolegraph-privs.md (renamed from docs/code/users-rolegraph-privs.md) | 9 | ||||
| -rw-r--r-- | content/hire-me/index.md (renamed from docs/hire-me.md) | 9 | ||||
| -rw-r--r-- | content/nomic/_index.md (renamed from docs/nomic/index.md) | 13 | ||||
| -rw-r--r-- | content/nomic/notes.md (renamed from docs/nomic/notes.md) | 33 | ||||
| -rw-r--r-- | content/nomic/rules.md (renamed from docs/nomic/rules.md) | 9 | ||||
| -rw-r--r-- | content/papers/index.md (renamed from docs/papers.md) | 9 | ||||
| -rw-r--r-- | content/satisfactory/_index.md | 11 | ||||
| -rw-r--r-- | content/satisfactory/way-of-building.md (renamed from docs/satisfactory/way-of-building.md) | 16 | ||||
| -rw-r--r-- | docs/code/index.md | 15 | ||||
| -rw-r--r-- | docs/git/config.md | 22 | ||||
| -rw-r--r-- | docs/git/detached-sigs.md | 172 | ||||
| -rw-r--r-- | docs/git/index.md | 14 | ||||
| -rw-r--r-- | docs/git/pull-request-workflow.md | 91 | ||||
| -rw-r--r-- | docs/git/scratch.md | 55 | ||||
| -rw-r--r-- | docs/git/stop-using-git-pull-to-deploy.md | 98 | ||||
| -rw-r--r-- | docs/git/survival.md | 81 | ||||
| -rw-r--r-- | docs/index.md | 25 | ||||
| -rw-r--r-- | docs/resume.md | 43 | ||||
| -rw-r--r-- | docs/satisfactory/Satisfactory - Phase 2 Final Report.pdf | bin | 4392718 -> 0 bytes | |||
| -rw-r--r-- | hugo.toml | 4 | ||||
| -rw-r--r-- | layouts/_default/baseof.html | 33 | ||||
| -rw-r--r-- | layouts/_default/list.html | 17 | ||||
| -rw-r--r-- | layouts/_default/single.html | 6 | ||||
| -rw-r--r-- | layouts/index.html | 17 | ||||
| -rw-r--r-- | mkdocs.yml | 13 | ||||
| -rwxr-xr-x | tools/build | 4 | ||||
| -rwxr-xr-x | tools/publish | 11 |
38 files changed, 248 insertions, 821 deletions
@@ -1 +1,2 @@ -/site/ +/.hugo_build.lock +/public/ diff --git a/.templates/base.html b/.templates/base.html deleted file mode 100644 index 6ce453d..0000000 --- a/.templates/base.html +++ /dev/null @@ -1,66 +0,0 @@ -<!DOCTYPE html> -<html> -<head> - <title> - {% block title_prefix -%} - {% if 'wiki-name' in config %}{{ config['wiki-name']|e }} » {% endif %} - {%- endblock %} - {% block title -%} - {{ title }} - {%- endblock %} - </title> - - <link - rel='stylesheet' - type='text/css' - href='//fonts.googleapis.com/css?family=Buenard:400,700&subset=latin,latin-ext'> - <link - rel="stylesheet" - type="text/css" - href="{{ make_relative('/media/css/reset.css') }}"> - <link - rel="stylesheet" - type="text/css" - href="{{ make_relative('/media/css/grimoire.css') }}"> - <link - rel="stylesheet" - type="text/css" - href="{{ make_relative('/media/css/codehilite.css') }}"> -</head> -<body> - -<div id="shell"> - {% if crumbs %} - <ol id="breadcrumbs"> - {% for name, href in crumbs %} - <li class="crumb-{{ loop.index0 }} {% if loop.last %}last{% else %}not-last{% endif %}"> - {% if not href %} - {{ name|e }} - {% else %} - <a href="{{ make_relative(href)|e }}">{{ name|e }}</a> - {% endif %} - </li> - {% endfor %} - </ol> - {% endif %} - - {% block content %} - {% endblock %} - - {% block footer %} - <div id="footer"> - <p>Questions? Comments? Feedback? <a href="mailto:owen+blog@grimoire.ca">Email me</a>!</p> - <p> - {% if 'wiki-name' in config %} - {{ config['wiki-name']|e }} — - {% endif %} - Powered by <a href="https://github.com/zacharyvoase/markdoc">Markdoc</a>. - {% block scm_info %} - <a href="https://github.org/grimoire-ca/bliki">See it on Github</a>. - {% endblock %} - </p> - </div> - {% endblock %} -</div> -</body> -</html> diff --git a/.templates/document.html b/.templates/document.html deleted file mode 100644 index 602b9ec..0000000 --- a/.templates/document.html +++ /dev/null @@ -1,12 +0,0 @@ -{% extends 'base.html' %} - -{% block content %} -<div id="article"> - {{ content }} -</div> -{% endblock %} - -{% block scm_info %} -<a href="https://github.com/grimoire-ca/bliki/blob/main/wiki/{{ path }}.md">See this page on Github</a> (<a - href="https://github.com/grimoire-ca/bliki/commits/main/wiki/{{ path }}.md">history</a>). -{% endblock %}
\ No newline at end of file diff --git a/.templates/listing.html b/.templates/listing.html deleted file mode 100644 index 3a52505..0000000 --- a/.templates/listing.html +++ /dev/null @@ -1,44 +0,0 @@ -{% extends 'base.html' %} - -{% block title %}ls /{{ directory|e }}{% endblock %} - -{% block content %} -<div id="listing"> - <h1><code>ls /{{ directory|e }}</code></h1> - - {% if sub_directories %} - <div id="directories"> - <h2>Directories</h2> - <ul> - {% for dir in sub_directories %} - <li><a href="{{ make_relative(dir.href) }}">{{ dir.basename|e }}/</a></li> - {% endfor %} - </ul> - </div> - {% endif %} - - {% if pages %} - <div id="pages"> - <h2>Pages</h2> - <ul> - {% for page in pages %} - <li><a href="{{ make_relative(page.href) }}">{{ page.title }}</a></li> - {% endfor %} - </ul> - </div> - {% endif %} - - {% if files %} - <div id="files"> - <h2>Files</h2> - {% for file in files %} - <li><a href="{{ make_relative(file.href) }}">{{ file.basename|e }}</a></li> - {% endfor %} - </div> - {% endif %} -</div> -{% endblock %} - -{% block scm_info %} -<a href="https://github.com/grimoire-ca/bliki/tree/main/wiki/{{ directory }}">See this directory on Github</a>. -{% endblock %}
\ No newline at end of file @@ -1,28 +1,27 @@ # Grimoire.ca Blog/Wiki -This repository contains the infrastructure for publishing a website, built from a suite of Markdown files and other resources, to Amazon. +This repository contains the infrastructure for publishing a website, built from a suite of Markdown files and other resources, to a web server. ## Pre-requisites You will need: -* [MkDocs](https://mkdocs.org) (`brew install mkdocs`) -* The AWS CLI (`brew install awscli`), logged in on an account with access to the `grimoire.ca` S3 bucket. +* [Hugo](https://gohugo.io/) (`sudo port install hugo`). ## Building -To prepare this site for deployment, run mkdocs from the project's root directory, use the included `tools/build` script. +To prepare this site for deployment, run `hugo` from the project's root directory, using the included `tools/build` script. -The resulting files will be placed in `site` under the project's root directory, replacing any files already present. +The resulting files will be placed in `public` under the project's root directory, replacing any files already present. You can also preview the site locally: ```bash -mkdocs serve +hugo serve ``` -This will automatically rebuild the site every time the files in `docs` change, and will serve them on a web server at <http://127.0.0.1:8000>. +This will automatically rebuild the site every time the files in `content` change, and will serve them on a web server at <http://127.0.0.1:1313>. ## Publishing -Once the site is built, it can be published to s3 using `tools/publish`. +Once the site is built, it can be published using `tools/publish`. diff --git a/archetypes/default.md b/archetypes/default.md new file mode 100644 index 0000000..2c792d5 --- /dev/null +++ b/archetypes/default.md @@ -0,0 +1,5 @@ +--- +title: {{ replace .File.ContentBaseName "-" " " | title }} +date: {{ .Date }} +draft: true +-- diff --git a/content/_index.md b/content/_index.md new file mode 100644 index 0000000..1f1c75a --- /dev/null +++ b/content/_index.md @@ -0,0 +1,9 @@ +--- +title: The Grimoire +--- +The best way to contact me is [by email], but [I'm present in many places]. + +[by email]: mailto:owen@grimoire.ca +[I'm present in many places]: https://wheretofind.me/@owen + +<!--more--> diff --git a/content/code/_index.md b/content/code/_index.md new file mode 100644 index 0000000..0b5fa42 --- /dev/null +++ b/content/code/_index.md @@ -0,0 +1,7 @@ +--- +title: Code +--- + +I program computers. I have done so all of my adult life, and expect to do so as long as I can string concepts together. Like many lifelong programmers, I periodically write up interesting things I've developed, collaborated on, or run across. + +<!--more--> diff --git a/docs/code/commit-messages.md b/content/code/commit-messages.md index 532b2c6..94b83f8 100644 --- a/docs/code/commit-messages.md +++ b/content/code/commit-messages.md @@ -1,4 +1,11 @@ -# Writing Good Commit Messages +--- +title: Writing Good Commit Messages +date: 2013-02-12T09:42:01-0500 +--- + +A style guide. + +<!--more--> Rule zero: “good” is defined by the standards of the project you're on. Have a look at what the existing messages look like, and try to emulate that first before doing anything else. diff --git a/docs/code/configuring-browser-apps.md b/content/code/configuring-browser-apps.md index 8869a61..6f53b6e 100644 --- a/docs/code/configuring-browser-apps.md +++ b/content/code/configuring-browser-apps.md @@ -1,8 +1,13 @@ -# Configuring Browser Apps +--- +title: Configuring Browser Apps +date: 2016-06-04T12:10:47-0400 +--- -I've found myself in he unexpected situation of having to write a lot of +I've found myself in the unexpected situation of having to write a lot of browser apps/single page apps this year. I have some thoughts on configuration. +<!--more--> + ## Why Bother * Centralize environment-dependent facts to simplify management & testing diff --git a/docs/code/tools-convention.md b/content/code/tools-convention.md index 4d1175e..12a3253 100644 --- a/docs/code/tools-convention.md +++ b/content/code/tools-convention.md @@ -1,4 +1,12 @@ -# The `tools` directory +--- +title: The `tools` directory +linkTitle: Using the shell environment as a project tool +date: 2022-03-04T15:16:35-0500 +--- + +A general and less tooling-intensive approach to automating routine project tasks. + +<!--more--> ## Background @@ -39,11 +47,13 @@ These scripts follow a few principles to ensure that they remain manageable: * Include a block comment near the top with a usage summary: - ## tools/example - ## tools/example FILENAME - ## - ## Runs the examples. If FILENAME is provided, then only the - ## example in FILENAME will actually be executed. + ```bash + ## tools/example + ## tools/example FILENAME + ## + ## Runs the examples. If FILENAME is provided, then only the + ## example in FILENAME will actually be executed. + ``` * Minimize the use of arguments. Ideally, use only either no arguments, one argument, or an arbitrary number of arguments. Under no circumstances use options or flags. @@ -117,35 +127,35 @@ This, in turn, runs the following: * `tools/check-tests`: - #!/bin/bash -ex + #!/bin/bash -ex - # tools/check-tests - # - # Checks that the code in this project passes incorrectness checks. + # tools/check-tests + # + # Checks that the code in this project passes incorrectness checks. - cargo build --locked --all-targets - cargo test + cargo build --locked --all-targets + cargo test * `tools/check-lints`: - #!/bin/bash -ex + #!/bin/bash -ex - # tools/check-lints - # - # Checks that the code in this project passes style checks. + # tools/check-lints + # + # Checks that the code in this project passes style checks. - cargo fmt -- --check - cargo clippy -- --deny warnings + cargo fmt -- --check + cargo clippy -- --deny warnings * `tools/check-dependencies`: - #!/bin/bash -ex + #!/bin/bash -ex - # check-dependencies - # - # Checks that the dependencies in this project are all in use. + # check-dependencies + # + # Checks that the dependencies in this project are all in use. - cargo udeps --locked --all-targets + cargo udeps --locked --all-targets Yet another project uses a tool to run tests against a container: @@ -161,12 +171,12 @@ cd "$(dirname "$0")/.." VERSION="$(detect-version)" py.test \ - --image-version "${VERSION}" + --image-version "${VERSION}" ``` ## Alternatives -* NAME's [`just`](https://github.com/casey/just) stores shell snippets in a project-wide `Justfile`. +* Casey Rodarmor's [`just`](https://github.com/casey/just) stores shell snippets in a project-wide `Justfile`. This allows for reliable generation of project-specific help and usage information from the `Justfile` and allows `just foo` to work from any directory in the project without project-specific shell configuration. diff --git a/docs/code/users-rolegraph-privs.md b/content/code/users-rolegraph-privs.md index d36f430..b93380f 100644 --- a/docs/code/users-rolegraph-privs.md +++ b/content/code/users-rolegraph-privs.md @@ -1,4 +1,11 @@ -# A Users, Roles & Privileges Scheme Using Graphs +--- +title: A Users, Roles & Privileges Scheme Using Graphs +date: 2013-02-06T12:29:39-0500 +--- + +An SQL schema and associated queries for handling permissions when roles can nest arbitrarily. + +<!--more--> The basic elements: diff --git a/docs/hire-me.md b/content/hire-me/index.md index 5b46bba..dee1ad5 100644 --- a/docs/hire-me.md +++ b/content/hire-me/index.md @@ -1,7 +1,14 @@ -# Hire Me +--- +title: Hire Me +date: 2023-02-07T09:21:26-0500 +--- + +I've been a professional software developer since the early 2000s and an enthusiastic amateur even longer, and a manager of developers since 2019. I'm also deeply interested in organizational dynamics and group consensus: software, like ourselves, lives in a society, and both serves the needs of and serves to help shape that society. I'm always interested in hearing from people and organizations that I can help, whether that means coming in for a few days to talk about end-to-end testing or joining your organization full-time to help turn an idea into reality. +<!--more--> + I live in and around Toronto. I am more than happy to work remotely, and I can probably help your organization learn to integrate remote work if it doesn't already know how. ## For Fun diff --git a/docs/nomic/index.md b/content/nomic/_index.md index 8e28e6e..4b580cd 100644 --- a/docs/nomic/index.md +++ b/content/nomic/_index.md @@ -1,10 +1,13 @@ -# Nomic +--- +title: Nomic +--- + +Some collected notes on playing Peter Suber's game of rule amendment, _Nomic_, on Github. + +<!--more--> [Nomic](https://legacy.earlham.edu/~peters/nomic.htm) is a game invented in 1982 by Peter Suber, as an appendix to his PhD thesis _The Paradox of Self-Amendment_. In Nomic, the primary move available to the players is to change the rules of the game in a structured way. Nomic itself was intended as a minimalist study of procedural law, but it has been played very successfully by many groups over the years. I first played Nomic through [Agora](http://www.dfw.net/~ccarroll/agora/), a long-running Nomic of a heavily procedural bent (as opposed to variants like BlogNomic, that have developed in much more whimsical directions). I've found the game, and the communities that have sprung up around the game, deeply fascinating as a way to examine how groups reach consensus and exercise decisions. -I briefly experimented with the notion of running a procedural Nomic - a mini-Agora - via Github, and produced two documents: - -* [Notes Towards Initial Rules for a Github Nomic](notes.md) -* [Github Nomic Rules](rules.md) +I briefly experimented with the notion of running a procedural Nomic - a mini-Agora - via Github, and produced these documents. diff --git a/docs/nomic/notes.md b/content/nomic/notes.md index 7ff43e5..fde14d2 100644 --- a/docs/nomic/notes.md +++ b/content/nomic/notes.md @@ -1,12 +1,19 @@ -# Notes Towards Initial Rules for a Github Nomic +--- +title: Notes Towards Initial Rules for a Github Nomic +date: 2016-11-08T01:19:07-0500 +# Weights chosen as a joke about Nomic's rule numbers. +weight: 100 +--- + +<!--more--> This document is not part of the rules of a Nomic, and is present solely as a guide to the design of [this initial ruleset](rules.md), for play on Github. It should be removed before the game starts, and at no time should it be consulted to guide gameplay directly. Peter Suber's [Nomic](http://legacy.earlham.edu/~peters/writing/nomic.htm) is a game of rule-making for one or more players. For details on the rationale behind the game and the reasons the game might be interesting, see Suber's own description. -# Changes from Suber's Rules +## Changes from Suber's Rules -## Format +### Format I've marked up Suber's rules into Markdown, one of Github's “native” text markup formats. This highly-structured format produces quite readable results when viewed through the Github website, and allows useful things like HTML links that point to specific rules. @@ -14,7 +21,7 @@ I've also made some diff-friendliness choices around the structure of those Mark I have not codified this format in the rules themselves. -## Asynchrony +### Asynchrony In its original form, Nomic is appropriate for face-to-face play. The rules assume that it is practical for the players to identify one another using out-of-game context, and that it is practical for the players to take turns. Each player is expected to wait indefinitely (or, more likely, to apply non-game social pressure) if the preceding player takes inordinately long to complete their turn. Similarly, Judgement interrupts the flow of game play and brings turns to a stop. @@ -32,31 +39,31 @@ I have attempted to leave the rules as close to Suber's original rules as possib I have, as far as I am able, emulated Suber's preference for succinctness over thoroughness, and resisted the urge to fix or clarify rules even where defects seem obvious to me. In spite of my temptation to remove it, I have even left the notion of “winning” intact. -## Rule-numbering +### Rule-numbering The intent of this Nomic is to explore the suitability of Github's suite of tools for proposing, reviewing, and accepting changes to a corpus of text are suitable for self-governed rulemaking processes, as modelled by Nomic. Note that this is a test of Github, not of Git: it is appropriate and intended that the players rely on non-Git elements of Github's workflow (issues, wiki pages, Github Pages, and so on), and similarly it is appropriate and intended that the authentic copy of the game in play is the Github project hosting it, not the Git repo the project contains, and certainly not forks of the project or other clones of the repository. To support this intention, I have re-labelled the initial rules with negative numbers, rather than digits, so that proposals can be numbered starting from 1 without colliding with existing rules, and so that they can be numbered by their Pull Requests and Github issue numbers. (A previous version of these rules used Roman numerals for the initial rules. However, correctly accounting for the priority of new rules over initial rules, following Suber, required more changes than I was comfortable making to Suber's ruleset.) I have made it explicit in these initial rules that Github, not the players, assigns numbers to proposals. This is the only rule which mentions Github by name. I have not explicitly specified that the proposals should be implemented through pull requests; this is an intentional opportunity for player creativity. -## Projects & Ideas +### Projects & Ideas A small personal collection of other ideas to explore: -### Repeal or replace the victory criteria entirely +#### Repeal or replace the victory criteria entirely “Winning” is not an objective I'm personally interested in, and Suber's race to 200 points by popularity of proposal is structurally quite dull. If the game is to have a victory condition, it should be built from the ground up to meet the players' motivations, rather than being retrofitted onto the points-based system. -### Codify the use of Git commits, rather than prose, for rules-changes +#### Codify the use of Git commits, rather than prose, for rules-changes This is unstated in this ruleset, despite being part of my intention for playing. So is the relationship between proposals and the Git repository underpinning the Github project hosting the game. -### Clarify the immigration and exit procedures +#### Clarify the immigration and exit procedures The question of who the players _are_, or how one becomes a player, is left intentionally vague. In Suber's original rules, it appears that the players are those who are engaged in playing the game: tautological on paper, but inherently obvious by simple observation of the playing-space. On Github, the answer to this question may not be so simple. A public repository is _visible_ to anyone with an internet connection, and will accept _proposed_ pull requests (and issue reports) equally freely. This suggests that either everyone is, inherently, a player, or that player-ness is somehow a function of engaging with the game. I leave it to the players to resolve this situation to their own satisfaction, but my suggestion is to track player-ness using repository collaborators or organization member accounts. -### Figure out how to regulate the use of Github features +#### Figure out how to regulate the use of Github features Nomic, as written, largely revolves around sequential proposals. That's fine as far as it goes, but Github has a very wide array of project management features - and that set of features changes over time, outside the control of the players, as Github roll out improvements (and, sometimes, break things). @@ -69,19 +76,19 @@ Features of probable interest: * Pull request reactions and approvals. * The mutability of most Github features. -### Expand the rules-change process to permit a single proposal to amend many rules +#### Expand the rules-change process to permit a single proposal to amend many rules This is a standard rules patch, as Suber's initial rule-set is (I believe intentionally) very restrictive. This may turn out to be less relevant on Github, if players are allowed to submit turns in rapid succession with themselves. -### Transition from immediate amendment to a system of sessions +#### Transition from immediate amendment to a system of sessions Why not? Parliamentary procedure is fun, right? In an asynchronous environment, the discrete phases of a session system (where proposals are gathered, then debated, then voted upon, then enacted as a unit) might be a better fit for the Github mode of play. -### Evaluate other models of proposal vetting besides majority vote +#### Evaluate other models of proposal vetting besides majority vote Github open source projects regularly have a small core team of maintainers supporting a larger group of users. Is it possible to mirror this structure in Nomic? Is it wise to do so? diff --git a/docs/nomic/rules.md b/content/nomic/rules.md index 912b4c8..75dbda7 100644 --- a/docs/nomic/rules.md +++ b/content/nomic/rules.md @@ -1,4 +1,11 @@ -# Github Nomic Rules +--- +title: Github Nomic Rules +date: 2016-11-08T01:19:07-0500 +# Weights chosen as a joke about Nomic's rule numbers. +weight: 200 +--- + +<!--more--> ## Immutable Rules diff --git a/docs/papers.md b/content/papers/index.md index 37d2d84..0dd962f 100644 --- a/docs/papers.md +++ b/content/papers/index.md @@ -1,4 +1,11 @@ -# Papers of Note +--- +title: Papers of Note +date: 2023-11-01T01:02:40-0400 +--- + +Computer science and development-adjacent papers and academic works I encourage people to read. + +<!--more--> * Perlman, Radia (1985). “[An Algorithm for Distributed Computation of a Spanning Tree in an Extended LAN][1]”. ACM SIGCOMM Computer Communication Review. 15 (4): 44–53. doi:10.1145/318951.319004. diff --git a/content/satisfactory/_index.md b/content/satisfactory/_index.md new file mode 100644 index 0000000..58eb13c --- /dev/null +++ b/content/satisfactory/_index.md @@ -0,0 +1,11 @@ +--- +title: Satisfactory +--- + +What's a nerd without a factory game fascination? + +Satisfactory is a game about destroying the ecosystem of a pristine world, for profit. You are put in the shoes of a faceless corporate drone, given tools with rapidly increasing agency for extract and exploiting natural resources, and situated within an incentive structure that rewards you for doing so as efficiently as possible. + +It's great fun. + +<!--more--> diff --git a/docs/satisfactory/way-of-building.md b/content/satisfactory/way-of-building.md index eddf279..e7fdc64 100644 --- a/docs/satisfactory/way-of-building.md +++ b/content/satisfactory/way-of-building.md @@ -1,14 +1,18 @@ -# A More Satisfactory Way of Building - -_Correction: This essay originally attributed the AWESOME Sink to Update 4._ +--- +title: A More Satisfactory Way of Building +date: 2022-03-30T23:29:36-0400 +--- In 2020, [Aphyr] wrote _[A Satisfactory Way of Building]_, exploring the the idea of pattern languages through the forces and consequences imposed by Satisfactory. In the intervening two years, the developers have released two major updates to the game, adding entirely new systems, adding new ways of responding to the forces and tensions in the game, and tweaking (or in some cases, completely reworking) the existing systems and tools. [Aphyr]: https://aphyr.com/ [A Satisfactory Way of Building]: https://aphyr.com/posts/351-a-satisfactory-way-of-building - Changing contexts and forces lead to changing solutions, and while much of _Building_ remains good advice today, some of it deserves revision. Those changes also create new forces, which give rise to new patterns not contemplated in Aphyr's original piece. +<!--more--> + +_Correction: This essay originally attributed the AWESOME Sink to Update 4._ + ## What's New The original essay was written against the background of Update 3, which included rail transport, Hypertube people-movers, fluids, and nuclear power, as well as extensive dry-goods automation. The two updates ([Update 4], [Update 5]) since have added features that fall into a few categories. @@ -187,7 +191,7 @@ As an alternative to a core, route vertical connections through floor holes at o Power switches and power storages interact with Aphyr's pattern language in a few interesting ways, and deserve some treatment of their own. -Power storages fight neatly within the **Backup Grid** guideline, and provide a viable alternative to restart coal or gas-based power production. Providing enough battery power to restart nuclear power is less practical, but by that stage of the game, geothermal generators are available and provide ample power to restart fuel production. +Power storages fit neatly within the **Backup Grid** guideline, and provide a viable alternative to restart coal or gas-based power production. Providing enough battery power to restart nuclear power is less practical, but by that stage of the game, geothermal generators are available and provide ample power to restart fuel production. **Single Power Link** proposes that power be connected to a factory, zone, or floor by a single wire that can be severed. Switches are a much more legible alternative to constructing and dismantling power lines, and do not require that the player carry cable on their person in order to turn factories back on. This is a small change on its own, but the convenience of switches makes other patterns more approachable: @@ -229,4 +233,4 @@ More extreme hazards may require the construction of a catch structure at a lowe ### Walkable Hazards -Zones and floors that deal with hazardous materials need special consideration for hoverpack access. Dangerous areas must be provided with pedestrian access, and should be provided with **On-site PPE**.
\ No newline at end of file +Zones and floors that deal with hazardous materials need special consideration for hoverpack access. Dangerous areas must be provided with pedestrian access, and should be provided with **On-site PPE**. diff --git a/docs/code/index.md b/docs/code/index.md deleted file mode 100644 index e0efe37..0000000 --- a/docs/code/index.md +++ /dev/null @@ -1,15 +0,0 @@ -# Code - -Pieces of code and code-adjacent work, with or without exposition, that don't quite fit into the library ecosystem, but which I enjoyed writing. - -* [Using the shell environment as a project tool](tools-convention.md) — A general and less tooling-intensive approach to automating routine project tasks. - -* [A Users, Roles & Privileges Scheme Using Graphs](users-rolegraph-privs.md) — An SQL schema and associated queries for handling permissions when roles can nest arbitrarily. - -* [Configuring Browser Apps](configuring-browser-apps.md) — Notes on the available techniques for delivering runtime configuration to code running in a user's browser, and the tradeoffs involved. - -* [Writing Good Commit Messages](commit-messages.md) — A style guide. - -* [Some collected advice about Git](../git/index.md) — Not the source control tool we want, but definitely the source control tool we've got, and I think we should make the best of it. - -I also maintain a [Github account](https://github.com/ojacobson/) for more substantial projects. diff --git a/docs/git/config.md b/docs/git/config.md deleted file mode 100644 index 456d580..0000000 --- a/docs/git/config.md +++ /dev/null @@ -1,22 +0,0 @@ -# git-config Settings You Want - -Git comes with some fairly [lkml](http://www.tux.org/lkml/)-specific configuration defaults. You should fix this. All of the items below can be set either for your entire login account (`git config --global`) or for a specific repository (`git config`). - -Full documentation is under `git help config`, unless otherwise stated. - -* `git config user.name 'Your Full Name'` and `git config user.email 'your-email@example.com'`, obviously. Git will remind you about this if you forget. - -* `git config merge.defaultToUpstream true` - causes an unqualified `git merge` to merge the current branch's configured upstream branch, rather than being an error. This makes `git merge` much more consistent with `git rebase`, and as the two tools fill very similar workflow niches, it's nice to have them behave similarly. - -* `git config rebase.autosquash true` - causes `git rebase -i` to parse magic comments created by `git commit --squash=some-hash` and `git commit --fixup=some-hash` and reorder the commit list before presenting it for further editing. See the descriptions of “squash” and “fixup” in `git help rebase` for details; autosquash makes amending commits other than the most recent easier and less error-prone. - -* `git config branch.autosetupmerge always` - newly-created branches whose start point is a branch (`git checkout master -b some-feature`, `git branch some-feature origin/develop`, and so on) will be configured to have the start point branch as their upstream. By default (with `true` rather than `always`) this only happens when the start point is a remote-tracking branch. - -* `git config rerere.enabled true` - enable “reuse recorded resolution.” The `git help rerere` docs explain it pretty well, but the short version is that git can record how you resolve conflicts during a “test” merge and reuse the same approach when resolving the same conflict later, in a “real” merge. - -## For advanced users - -A few things are nice when you're getting started, but become annoying when -you no longer need them. - -* `git config advice.detachedHead` - if you already understand the difference between having a branch checked out and having a commit checked out, and already understand what “detached head” means, the warning on every `git checkout ...some detached thing...` isn't helping anyone. This is also useful repositories used for deployment, where specific commits (from tags, for example) are regularly checked out. diff --git a/docs/git/detached-sigs.md b/docs/git/detached-sigs.md deleted file mode 100644 index 0b8a386..0000000 --- a/docs/git/detached-sigs.md +++ /dev/null @@ -1,172 +0,0 @@ -# Notes Towards Detached Signatures in Git - -Git supports a limited form of object authentication: specific object categories in Git's internal model can have GPG signatures embedded in them, allowing the authorship of the objects to be verified using GPG's underlying trust model. Tag signatures can be used to verify the authenticity and integrity of the _snapshot associated with a tag_, and the authenticity of the tag itself, filling a niche broadly similar to code signing in binary distribution systems. Commit signatures can be used to verify the authenticity of the _snapshot associated with the commit_, and the authorship of the commit itself. (Conventionally, commit signatures are assumed to also authenticate either the entire line of history leading to a commit, or the diff between the commit and its first parent, or both.) - -Git's existing system has some tradeoffs. - -* Signatures are embedded within the objects they sign. The signature is part of the object's identity; since Git is content-addressed, this means that an object can neither be retroactively signed nor retroactively stripped of its signature without modifying the object's identity. Git's distributed model means that these sorts of identity changes are both complicated and easily detected. - -* Commit signatures are second-class citizens. They're a relatively recent addition to the Git suite, and both the implementation and the social conventions around them continue to evolve. - -* Only some objects can be signed. While Git has relatively weak rules about workflow, the signature system assumes you're using one of Git's more widespread workflows by limiting your options to at most one signature, and by restricting signatures to tags and commits (leaving out blobs, trees, and refs). - -I believe it would be useful from an authentication standpoint to add "detached" signatures to Git, to allow users to make these tradeoffs differently if desired. These signatures would be stored as separate (blob) objects in a dedicated `refs` namespace, supporting retroactive signatures, multiple signatures for a given object, "policy" signatures, and authentication of arbitrary objects. - -The following notes are partially guided by Git's one existing "detached metadata" facility, `git notes`. Similarities are intentional; divergences will be noted where appropriate. Detached signatures are meant to interoperate with existing Git workflow as much as possible: in particular, they can be fetched and pushed like any other bit of Git metadata. - -A detached signature cryptographically binds three facts together into an assertion whose authenticity can be checked by anyone with access to the signatory's keys: - -1. An object (in the Git sense; a commit, tag, tree, or blob), -2. A policy label, and -3. A signatory (a person or agent making the assertion). - -These assertions can be published separately from or in tandem with the objects they apply to. - -## Policies - -Taking a hint from Monotone, every signature includes a "policy" identifying how the signature is meant to be interpreted. Policies are arbitrary strings; their meaning is entirely defined by tooling and convention, not by this draft. - -This draft uses a single policy, `author`, for its examples. A signature under the `author` policy implies that the signatory had a hand in the authorship of the designated object. (This is compatible with existing interpretations of signed tags and commits.) (Authorship under this model is strictly self-attested: you can claim authorship of anything, and you cannot assert anyone else's authorship.) - -The Monotone documentation suggests a number of other useful policies related to testing and release status, automated build results, and numerous other factors. Use your imagination. - -## What's In A Signature - -Detached signatures cover the disk representation of an object, as given by - -```bash -git cat-file <TYPE> <SHA1> -``` - -For most of Git's object types, this means that the signed content is plain text. For `tree` objects, the signed content is the awful binary representation of the tree, _not_ the pretty representation given by `git ls-tree` or `git show`. - -Detached signatures include the "policy" identifier in the signed content, to prevent others from tampering with policy choices via `refs` hackery. (This will make more sense momentarily.) The policy identifier is prepended to the signed content, terminated by a zero byte (as with Git's own type identifiers, but without a length field as length checks are performed by signing and again when the signature is stored in Git). - -To generate the _complete_ signable version of an object, use something equivalent to the following shell snippet: - -```bash -# generate-signable POLICY TYPE SHA1 -function generate-signable() { - printf '%s\0' "$1" - git cat-file "$2" "$3" -} -``` - -(In the process of writing this, I discovered how hard it is to get Unix's C-derived shell tools to emit a zero byte.) - -## Signature Storage and Naming - -We assume that a userid will sign an object at most once. - -Each signature is stored in an independent blob object in the repository it applies to. The signature object (described above) is stored in Git, and its hash recorded in `refs/signatures/<POLICY>/<SUBJECT SHA1>/<SIGNER KEY FINGERPRINT>`. - -```bash -# sign POLICY TYPE SHA1 FINGERPRINT -function sign() { - local SIG_HASH=$( - generate-signable "$@" | - gpg --batch --no-tty --sign -u "$4" | - git hash-object --stdin -w -t blob - ) - git update-ref "refs/signatures/$1/$3/$4" -} -``` - -Stored signatures always use the complete fingerprint to identify keys, to minimize the risk of colliding key IDs while avoiding the need to store full keys in the `refs` naming hierarchy. - -The policy name can be reliably extracted from the ref, as the trailing part has a fixed length (in both path segments and bytes) and each ref begins with a fixed, constant prefix `refs/signatures/`. - -## Signature Verification - -Given a signature ref as described above, we can verify and authenticate the signature and bind it to the associated object and policy by performing the following check: - -1. Pick apart the ref into policy, SHA1, and key fingerprint parts. -2. Reconstruct the signed body as above, using the policy name extracted from the ref. -3. Retrieve the signature from the ref and combine it with the object itself. -4. Verify that the policy in the stored signature matches the policy in the ref. -5. Verify the signature with GPG: - - ```bash - # verify-gpg POLICY TYPE SHA1 FINGERPRINT - verify-gpg() { - { - git cat-file "$2" "$3" - git cat-file "refs/signatures/$1/$3/$4" - } | gpg --batch --no-tty --verify - } - ``` - -6. Verify the key fingerprint of the signing key matches the key fingerprint in the ref itself. - -The specific rules for verifying the signature in GPG are left up to the user to define; for example, some sites may want to auto-retrieve keys and use a web of trust from some known roots to determine which keys are trusted, while others may wish to maintain a specific, known keyring containing all signing keys for each policy, and skip the web of trust entirely. This can be accomplished via `git-config`, given some work, and via `gpg.conf`. - -## Distributing Signatures - -Since each signature is stored in a separate ref, and since signatures are _not_ expected to be amended once published, the following refspec can be used with `git fetch` and `git push` to distribute signatures: - -``` -refs/signatures/*:refs/signatures/* -``` - -Note the lack of a `+` decoration; we explicitly do not want to auto-replace modified signatures, normally; explicit user action should be required. - -## Workflow Notes - -There are two verification workflows for signatures: "static" verification, where the repository itself already contains all the refs and objects needed for signature verification, and "pre-receive" verification, where an object and its associated signature may be being uploaded at the same time. - -_It is impractical to verify signatures on the fly from an `update` hook_. Only `pre-receive` hooks can usefully accept or reject ref changes depending on whether the push contains a signature for the pushed objects. (Git does not provide a good mechanism for ensuring that signature objects are pushed before their subjects.) Correctly verifying object signatures during `pre-receive` regardless of ref order is far too complicated to summarize here. - -## Attacks - -### Lies of Omission - -It's trivial to hide signatures by deleting the signature refs. Similarly, anyone with access to a repository can delete any or all detached signatures from it without otherwise invalidating the signed objects. - -Since signatures are mostly static, sites following the recommended no-force policy for signature publication should only be affected if relatively recent signatures are deleted. Older signatures should be available in one or more of the repository users' loca repositories; once created, a signature can be legitimately obtained from anywhere, not only from the original signatory. - -The signature naming protocol is designed to resist most other forms of assertion tampering, but straight-up omission is hard to prevent. - -### Unwarranted Certification - -The `policy` system allows any signatory to assert any policy. While centralized signature distribution points such as "release" repositories can make meaningful decisions about which signatures they choose to accept, publish, and propagate, there's no way to determine after the fact whether a policy assertion was obtained from a legitimate source or a malicious one with no grounds for asserting the policy. - -For example, I could, right now, sign an `all-tests-pass` policy assertion for the Linux kernel. While there's no chance on Earth that the LKML team would propagate that assertion, if I can convince you to fetch signatures from my repository, you will fetch my bogus assertion. If `all-tests-pass` is a meaningful policy assertion for the Linux kernel, then you will have very few options besides believing that I assert that all tests have passed. - -### Ambigiuous Policy - -This is an ongoing problem with crypto policy systems and user interfaces generally, but this design does _nothing_ to ensure that policies are interpreted uniformly by all participants in a repository. In particular, there's no mechanism described for distributing either prose or programmatic policy definitions and checks. All policy information is out of band. - -Git already has ambiguity problems around commit signing: there are multiple ways to interpret a signature on a commit: - -1. I assert that this snapshot and commit message were authored as described in this commit's metadata. (In this interpretation, the signature's authenticity guarantees do _not_ transitively apply to parents.) - -2. I assert that this snapshot and commit message were authored as described in this commit's metadata, based on exactly the parent commits described. (In this interpretation, the signature's authenticity guarantees _do_ transitively apply to parents. This is the interpretation favoured by XXX LINK HERE XXX.) - -3. I assert that this _diff_ and commit message was authored as described in this commit's metadata. (No assertions about the _snapshot_ are made whatsoever, and assertions about parentage are barely sensical at all. This meshes with widespread, diff-oriented policies.) - -### Grafts and Replacements - -Git permits post-hoc replacement of arbitrary objects via both the grafts system (via an untracked, non-distributed file in `.git`, though some repositories distribute graft lists for end-users to manually apply) and the replacements system (via `refs/replace/<SHA1>`, which can optionally be fetched or pushed). The interaction between these two systems and signature verification needs to be _very_ closely considered; I've not yet done so. - -Cases of note: - -* Neither signature nor subject replaced - the "normal" case -* Signature not replaced, subject replaced (by graft, by replacement, by both) -* Signature replaced, subject not replaced -* Both signature and subject replaced - -It's tempting to outright disable `git replace` during signing and verification, but this will have surprising effects when signing a ref-ish instead of a bare hash. Since this is the _normal_ case, I think this merits more thought. (I'm also not aware of a way to disable grafts without modifying `.git`, and having the two replacement mechanisms treated differently may be dangerous.) - -### No Signed Refs - -I mentioned early in this draft that Git's existing signing system doesn't support signing refs themselves; since refs are an important piece of Git's workflow ecosystem, this may be a major omission. Unfortunately, this proposal doesn't address that. - -## Possible Refinements - -* Monotone's certificate system is key+value based, rather than label-based. This might be useful; while small pools of related values can be asserted using mutually exclusive policy labels (whose mutual exclusion is a matter of local interpretation), larger pools of related values rapidly become impractical under the proposed system. - - For example, this proposal would be inappropriate for directly asserting third-party authorship; the asserted author would have to appear in the policy name itself, exposing the user to a potentially very large number of similar policy labels. - -* Ref signing via a manifest (a tree constellation whose paths are ref names and whose blobs sign the refs' values). Consider cribbing DNSSEC here for things like lightweight absence assertions, too. - -* Describe how this should interact with commit-duplicating and commit-rewriting workflows. diff --git a/docs/git/index.md b/docs/git/index.md deleted file mode 100644 index 5cfc4d8..0000000 --- a/docs/git/index.md +++ /dev/null @@ -1,14 +0,0 @@ -# Collected Advice about Git - -* [git-config Settings You Want](config.md) — Git is highly configurable, and the defaults have gotten drastically better over the years, but there are still some non-default behaviours that I've found make life better. - -* [Notes Towards Detached Signatures in Git](detached-sigs.md) — An idea I had, but never fully developed, for implementing after-the-fact object signing on top of Git. This was based on a similar feature in Monotone, which I'd found very effective for annotating commits on the fly. - -* [Life With Pull Requests](pull-request-workflow.md) — Some notes I made while getting up to speed with pull requests to help my team come to grips with the workflows. - -* [Git Is Not Magic](scratch.md) — An exploration of Git's on-disk data structures and the design choices taken very early in Git's existence. - -* [Stop using `git pull` for deployment!](stop-using-git-pull-to-deploy.md) — Describing the least-painful way to use Git as a deployment tool I had worked out, circa 2014. Written in an aversarial style as a response to repeated ”why don't we just”s that, while well-intentioned, came from an incomplete understanding of what `git pull` does. - -* [Git Survival Guide](survival.md) — Some words of caution about Git, `git`'s preferred workflows, and various recoverable mistakes. - diff --git a/docs/git/pull-request-workflow.md b/docs/git/pull-request-workflow.md deleted file mode 100644 index 2d3e2c0..0000000 --- a/docs/git/pull-request-workflow.md +++ /dev/null @@ -1,91 +0,0 @@ -# Life With Pull Requests - -I've been party to a number of discussions with folks contributing to pull-request-based projects on Github (and other hosts, but mostly Github). Because of Git's innate flexibility, there are lots of ways to work with pull requests. Here's mine. - -I use a couple of naming conventions here that are not stock `git`: - -* `origin` is the repository to which you _publish_ proposed changes, and - -* `upstream` is the repository from which you receive ongoing development, and - which will receive your changes if they are accepted. - -## One-time setup - -Do these things once, when starting out on a project. Keep the results around for later. - -I'll be referring to the original project repository as `upstream` and pretending its push URL is `UPSTREAM-URL` below. In real life, the URL will often be something like `git@github.com:someguy/project.git`. - -### Fork the project - -Use the repo manager's forking tool to create a copy of the project in your own namespace. This generally creates your copy with a bunch of useless tat; feel free to ignore all of this, as the only purpose of this copy is to provide somewhere for _you_ to publish _your_ changes. - -We'll be calling this repository `origin` later. Assume it has a URL, which I'll abbreviate `ORIGIN-URL`, for `git push` to use. - -(You can leave this step for later, but if you know you're going to do it, why not get it out of the way?) - -### Clone the project and configure it - -You'll need a clone locally to do work in. Create one from `origin`: - -```bash -git clone ORIGIN-URL some-local-name -``` - -While you're here, `cd` into it and add the original project as a remote: - -```bash -cd some-local-name -git remote add upstream UPSTREAM-URL -``` - -## Feature process - -Do these things for each feature you work on. To switch features, just use `git checkout my-feature`. - -### Create a new feature branch locally - -We use `upstream`'s `master` branch here, so that your feature includes all of `upstream`'s state initially. We also need to make sure our local cache of `upstream`'s state is correct: - -```bash -git fetch upstream -git checkout upstream/master -b my-feature -``` - -### Do work - -If you need my help here, stop now. - -### Integrate upstream changes - -If you find yourself needing something that's been added upstream, use _rebase_ to integrate it to avoid littering your feature branch with “meaningless” merge commits. - -```bash -git checkout my-feature -git fetch upstream -git rebase upstream/master -``` - -### Publish your branch - -When you're “done,” publish your branch to your personal repository: - -```bash -git push origin my-feature -``` - -Then visit your copy in your repo manager's web UI and create a pull request for `my-feature`. - -### Integrating feedback - -Very likely, your proposed changes will need work. If you use history-editing to integrate feedback, you will need to use `--force` when updating the branch: - -```bash -git push --force origin my-feature -``` - -This is safe provided two things are true: - -1. **The branch has not yet been merged to the upstream repo.** -2. You are only force-pushing to your fork, not to the upstream repo. - -Generally, no other users will have work based on your pull request, so force-pushing history won't cause problems. diff --git a/docs/git/scratch.md b/docs/git/scratch.md deleted file mode 100644 index e912a1e..0000000 --- a/docs/git/scratch.md +++ /dev/null @@ -1,55 +0,0 @@ -# Git Is Not Magic - -I'm bored. Let's make a git repository out of whole cloth. - -Git repos are stored in .git: - - fakegit$ mkdir .git - -They have a “symbolic ref” (which are text files, see [`man -git-symbolic-ref`](http://jk.gs/git-symbolic-ref.html)) named `HEAD`, pointing -to the currently checked-out branch. Let's use `master`. Branches are refs -under `refs/heads` (see [`man git-branch`](http://jk.gs/git-branch.html)): - - fakegit ((unknown))$ echo 'ref: refs/heads/master' > .git/HEAD - -The have an object database and a refs database, both of which are simple -directories (see [`man -gitrepository-layout`](http://jk.gs/gitrepository-layout.html) and [`man -gitrevisions`](http://jk.gs/gitrevisions.html)). Let's also enable the reflog, -because it's a great safety net if you use history-editing tools in git: - - fakegit ((ref: re...))$ mkdir .git/refs .git/objects .git/logs - fakegit (master #)$ - -Now `__git_ps1`, at least, is convinced that we have a working git repository. -Does it work? - - fakegit (master #)$ echo 'Hello, world!' > hello.txt - fakegit (master #)$ git add hello.txt - fakegit (master #)$ git commit -m 'Initial commit' - [master (root-commit) 975307b] Initial commit - 1 file changed, 1 insertion(+) - create mode 100644 hello.txt - - fakegit (master)$ git log - commit 975307ba0485bff92e295e3379a952aff013c688 - Author: Owen Jacobson <owen.jacobson@grimoire.ca> - Date: Wed Feb 6 10:07:07 2013 -0500 - - Initial commit - -[Eeyup](https://www.youtube.com/watch?v=3VwVpaWUu30). - ------ - -Should you do this? **Of course not.** Anywhere you could run these commands, -you could instead run `git init` or `git clone`, which set up a number of -other structures, including `.git/config` and any unusual permissions options. -The key part here is that a directory's identity as “a git repository” is -entirely a function of its contents, not of having been blessed into being by -`git` itself. - -You can infer a lot from this: for example, you can infer that it's “safe” to -move git repositories around using FS tools, or to back them up with the same -tools, for example. This is not as obvious to everyone as you might hope; people diff --git a/docs/git/stop-using-git-pull-to-deploy.md b/docs/git/stop-using-git-pull-to-deploy.md deleted file mode 100644 index 078c95b..0000000 --- a/docs/git/stop-using-git-pull-to-deploy.md +++ /dev/null @@ -1,98 +0,0 @@ -# Stop using `git pull` for deployment! - -## The problem - -* You have a Git repository containing your project. -* You want to “deploy” that code when it changes. -* You'd rather not download the entire project from scratch for each - deployment. - -## The antipattern - -“I know, I'll use `git pull` in my deployment script!” - -Stop doing this. Stop teaching other people to do this. It's wrong, and it -will eventually lead to deploying something you didn't want. - -Deployment should be based on predictable, known versions of your code. -Ideally, every deployable version has a tag (and you deploy exactly that tag), -but even less formal processes, where you deploy a branch tip, should still be -deploying exactly the code designated for release. `git pull`, however, can -introduce new commits. - -`git pull` is a two-step process: - -1. Fetch the current branch's designated upstream remote, to obtain all of the - remote's new commits. -2. Merge the current branch's designated upstream branch into the current - branch. - -The merge commit means the actual deployed tree might _not_ be identical to -the intended deployment tree. Local changes (intentional or otherwise) will be -preserved (and merged) into the deployment, for example; once this happens, -the actual deployed commit will _never_ match the intended commit. - -`git pull` will approximate the right thing “by accident”: if the current -local branch (generally `master`) for people using `git pull` is always clean, -and always tracks the desired deployment branch, then `git pull` will update -to the intended commit exactly. This is pretty fragile, though; many git -commands can cause the local branch to diverge from its upstream branch, and -once that happens, `git pull` will always create new commits. You can patch -around the fragility a bit using the `--ff-only` option, but that only tells -you when your deployment environment has diverged and doesn't fix it. - -## The right pattern - -Quoting [Sitaram Chamarty](http://gitolite.com/the-list-and-irc/deploy.html): - -> Here's what we expect from a deployment tool. Note the rule numbers -- -> we'll be referring to some of them simply by number later. -> -> 1. All files in the branch being deployed should be copied to the -> deployment directory. -> -> 2. Files that were deleted in the git repo since the last deployment -> should get deleted from the deployment directory. -> -> 3. Any changes to tracked files in the deployment directory after the -> last deployment should be ignored when following rules 1 and 2. -> -> However, sometimes you might want to detect such changes and abort if -> you found any. -> -> 4. Untracked files in the deploy directory should be left alone. -> -> Again, some people might want to detect this and abort the deployment. - -Sitaram's own documentation talks about how to accomplish these when -“deploying” straight out of a bare repository. That's unwise (not to mention -impractical) in most cases; deployment should use a dedicated clone of the -canonical repository. - -I also disagree with point 3, preferring to keep deployment-related changes -outside of tracked files. This makes it much easier to argue that the changes -introduced to configure the project for deployment do not introduce new bugs -or other surprise features. - -My deployment process, given a dedicated clone at `$DEPLOY_TREE`, is as -follows: - - cd "${DEPLOY_TREE}" - git fetch --all - git checkout --force "${TARGET}" - # Following two lines only required if you use submodules - git submodule sync - git submodule update --init --recursive - # Follow with actual deployment steps (run fabric/capistrano/make/etc) - -`$TARGET` is either a tag name (`v1.2.1`) or a remote branch name -(`origin/master`), but could also be a commit hash or anything else Git -recognizes as a revision. This will detach the head of the `$DEPLOY_TREE` -repository, which is fine as no new changes should be authored in this -repository (so the local branches are irrelevant). The warning Git emits when -`HEAD` becomes detached is unimportant in this case. - -The tracked contents of `$DEPLOY_TREE` will end up identical to the desired -commit, discarding local changes. The pattern above is very similar to what -most continuous integration servers use when building from Git repositories, -for much the same reason. diff --git a/docs/git/survival.md b/docs/git/survival.md deleted file mode 100644 index 60d1b62..0000000 --- a/docs/git/survival.md +++ /dev/null @@ -1,81 +0,0 @@ -# Git Survival Guide - -I think the `git` UI is pretty awful, and encourages using Git in ways that -will screw you. Here are a few things I've picked up that have saved my bacon. - -* You will inevitably need to understand Git's “internals” to make use of it - as an SCM tool. Accept this early. If you think your SCM tool should not - expose you to so much plumbing, [don't](http://mercurial.selenic.com) - [use](http://bazaar.canonical.com) [Git](http://subversion.apache.org). - * Git weenies will claim that this plumbing is what gives Git all of its - extra power. This is true; it gives Git the power to get you out of - situations you wouldn't be in without Git. -* `git log --graph --decorate --oneline --color --all` -* Run `git fetch` habitually. Stale remote-tracking branches lead to sadness. -* `git push` and `git pull` are **not symmetric**. `git push`'s - opposite operation is `git fetch`. (`git pull` is equivalent to `git fetch` - followed by `git merge`, more or less). -* [Git configuration values don't always have the best defaults](config). -* The upstream branch of `foo` is `foo@{u}`. The upstream branch of your - checked-out branch is `HEAD@{u}` or `@{u}`. This is documented in `git help - revisions`. -* You probably don't want to use a merge operation (such as `git pull`) to - integrate upstream changes into topic branches. The resulting history can be - very confusing to follow, especially if you integrate upstream changes - frequently. - * You can leave topic branches “real” relatively safely. You can do - a test merge to see if they still work cleanly post-integration without - actually integrating upstream into the branch permanently. - * You can use `git rebase` or `git pull --rebase` to transplant your - branch to a new, more recent starting point that includes the changes - you want to integrate. This makes the upstream changes a permanent part - of your branch, just like `git merge` or `git pull` would, but generates - an easier-to-follow history. Conflict resolution will happen as normal. -* Example test merge, using `origin/master` as the upstream branch and `foo` - as the candidate for integration: - - git fetch origin - git checkout origin/master -b test-merge-foo - git merge foo - # run tests, examine files - git diff origin/master..HEAD - - To discard the test merge, delete the branch after checking out some other - branch: - - git checkout foo - git branch -D test-merge-foo - - You can combine this with `git rerere` to save time resolving conflicts in - a later “real,” permanent merge. - -* You can use `git checkout -p` to build new, tidy commits out of a branch - laden with “wip” commits: - - git fetch - git checkout $(git merge-base origin/master foo) -b foo-cleaner-history - git checkout -p foo -- paths/to/files - # pick out changes from the presented patch that form a coherent commit - # repeat 'git checkout -p foo --' steps for related files to build up - # the new commit - git commit - # repeat 'git checkout -p foo --' and 'git commit' steps until no diffs remain - - * Gotcha: `git checkout -p` will do nothing for files that are being - created. Use `git checkout`, instead, and edit the file if necessary. - Thanks, Git. - * Gotcha: The new, clean branch must diverge from its upstream branch - (`origin/master`, in the example above) at exactly the same point, or - the diffs presented by `git checkout -p foo` will include chunks that - revert changes on the upstream branch since the “dirty” branch was - created. The easiest way to find this point is with `git merge-base`. - -## Useful Resources - -That is, resoures that can help you solve problems or understand things, not -resources that reiterate the man pages for you. - -* Sitaram Chamarty's [git concepts - simplified](http://sitaramc.github.com/gcs/) -* Tv's [Git for Computer - Scientists](http://eagain.net/articles/git-for-computer-scientists) diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 81104c3..0000000 --- a/docs/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Owen Jacobson - -* [Hire Me](hire-me.md). - - I've been a professional software developer since the early 2000s and an enthusiastic amateur even longer, and a manager of developers since 2019. I'm also deeply interested in organizational dynamics and group consensus: software, like ourselves, lives in a society, and both serves the needs of and serves to help shape that society. - -* [Code](code/index.md). - - I program computers. I have done so all of my adult life, and expect to do so as long as I can string concepts together. Like many lifelong programmers, I periodically write up interesting things I've developed, collaborated on, or run across. - - My larger projects are on [Github](https://github.com/ojacobson/). - -* [Papers of Note](papers.md). - - Computer science and development-adjacent papers and academic works I encourage people to read. - -* [A More Satisfactory Way of Building](satisfactory/way-of-building.md). - - What's a nerd without a factory game fascination? - - Satisfactory is a game about destroying the ecosystem of a pristine world, for profit. You are put in the shoes of a faceless corporate drone, given tools with rapidly increasing agency for extract and exploiting natural resources, and situated within an incentive structure that rewards you for doing so as efficiently as possible. - - It's great fun. - -The best way to contact me is [by email](mailto:owen@grimoire.ca), but [I'm present in many places](https://wheretofind.me/@owen). diff --git a/docs/resume.md b/docs/resume.md deleted file mode 100644 index 1a8bfd4..0000000 --- a/docs/resume.md +++ /dev/null @@ -1,43 +0,0 @@ -# Owen Jacobson - -<owen@grimoire.ca> - 416 554 2902 - -## Ada Support (2022-2023) - -As an engineering manager at Ada, I lead a team of engineers to build an internal platform for chat applications. Our goal was to enable growth into new markets, by making it possible to extend Ada's product in novel ways based on the needs of new customers. - -During my tenure the team set out on building an event processing system based on Kafka, intended to decouple the company's in-house chat frontend from the response generation services and to become the common interface for other customer service platforms, so that Ada could intervene to assist customers via email, phone, and other services our customers might already be using. - -## Heroku/Salesforce (2015-2022) - -In my time with Heroku (and with Salesforce, Heroku's parent organization), I've contributed to the delivery and operation of services that let developers bring their ideas to life on the internet, both as a developer and as a manager. I've been involved in maintaining and expanding existing features, exploring and developing new products, and in cultivating my peers and my team as people and as developers. - -* As an engineering manager (2018 to 2022), I've been responsible for building and supporting an effective, unified team across multiple continents. Moving into management was motivated by a desire to act as a force multiplier, which I've brought to life through coaching, process management, facilitating ongoing discussions about the direction and health of the team, and through actively being involved in my reports' progress as developers. - - Each of the teams I've worked on has been responsible for both developing and operating a mature product, delivered at scale via the internet, to a diverse range of customers. My team has served everyone from single developers working on hobby projects all the way up to billion-dollar enterprises who selected Heroku as their platform of choice for the enterprise. - - Those teams have been comprised of everything from unique, hard-to-replace domain experts to interns on their first outing. In order to organize and lead, I take a disciplined approach to communication, emphasizing clarity and empathy. I provide as much flexibility around scheduling as the organization can spare, to enable my teams to work when they're at their best. And, as my team's ambassador to the organization, I gather up the disparate and sometimes highly-speculative streams of work in flight to present as a coherent roadmap against organizational goals. - - I've also been responsible for the huge range of work that Salesforce expects from line management, including performance management and coaching, compensation planning, hiring and interviewing, balancing on-call schedules against burnout and retention risks, and skilling up the team to handle the parts of all of these processes that can be delegated, while keeping their time free to do the things they're good at as much as is possible. - -* As a lead developer (2015-2018), I worked on the [Heroku build system](https://devcenter.heroku.com/articles/git), which ingests code from end users and deploys that code to applications running on the Heroku platform. As part of that work, we implemented a number of features to control abuse, support language-specific features and needs, and to develop [new ways to deploy code](https://devcenter.heroku.com/articles/build-docker-images-heroku-yml) to Heroku. - -## FreshBooks (2009-2014) - -During the five years I was with the company, it grew from a 20-person one-room organization to a healthy, growing two-hundred-person technology company. As an early employee, I had my hand in many, many projects and helped the development team absorb the massive cultural changes that come with growth, while also building a SaaS product that let others realize their dreams. Some highlights: - -* As the team's database administrator, I was responsible for balancing concerns about reliability and availability against the need to deliver new services and functional improvements for customers. Alongside the operations team, I handled capacity planning, reliability, outage planning, and performance monitoring. Alongside the development team, I was responsible for designing processes tooling and providing advice on the most effective ways to use MySQL to accomplish their goals. - -* As an ops toolsmith, I worked extensively on deployment automation and standardizing process for internal services. I created a standard development VM to ensure developers had an environment consistent with reality, I automated packaging and rollout to testing servers, I explored options around platform-as-a-service products to look for fit, and more. As part of this work, I built training materials and ran sessions to teach other developers how to think like a sysadmin, covering Linux, Puppet, virtualization, and other topics. - -## Riptown Media (2006-2009) - -Riptown Media was an software development company tasked with building and operating a suite of gambling systems for a single client. I was brought on board as a Java developer, and rapidly expanded my role to encompass other fields. - -* As the primary developer for poker-room back office and anti-fraud tools, I worked with the customer support and business intelligence teams to better understand their daily needs and frustrations, so that I could turn those into meaningful improvements to their tools and processes. These improvements, in turn, lead to measurable changes in the frequency and length of customer support calls, in fraud rates, and in the percieved value of internal customer intelligence. - -* As a lead developer, my team put together the server half of an in-house casino gaming platform. We worked in tight collaboration with the client team, in-house and third-party testers, and interaction designers, and delivered our first game in under six months. Our platform was meant to reduce our reliance on third-party “white label” games vendors; internally, it was a success. Our game received zero customer-reported defects during its initial run. - -## For Fun - -I regularly mentor people new to programming, teaching them how to craft working systems. This is less about teaching people to write code and more about teaching them why we care about source control, how to think about configuration, how to and why to automate testing, and how to think about software systems and data flow at a higher level. I strongly believe that software development needs a formal apprenticeship program, and mentoring has done a lot to validate that belief. diff --git a/docs/satisfactory/Satisfactory - Phase 2 Final Report.pdf b/docs/satisfactory/Satisfactory - Phase 2 Final Report.pdf Binary files differdeleted file mode 100644 index 26f519c..0000000 --- a/docs/satisfactory/Satisfactory - Phase 2 Final Report.pdf +++ /dev/null diff --git a/hugo.toml b/hugo.toml new file mode 100644 index 0000000..a6a6a29 --- /dev/null +++ b/hugo.toml @@ -0,0 +1,4 @@ +baseURL = 'https://grimoire.ca/' +languageCode = 'en-ca' +title = 'The Grimoire' +taxonomies = [] diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html new file mode 100644 index 0000000..c665429 --- /dev/null +++ b/layouts/_default/baseof.html @@ -0,0 +1,33 @@ +<!DOCTYPE html> +<html> + <head> + <title>{{- block "title" . }}{{ .Site.Title }} + {{- if .Title }} - {{ .Title }}{{ end }} + {{- end }}</title> + {{- with .OutputFormats.Get "rss" }} + <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink }}" title="{{ site.Title }}"> + {{- end }} + </head> + <body> + {{- block "header" . }} + {{- if .Title }} + <header> + <h1>{{ .Title }}</h1> + {{- if .PublishDate }} + <p><small>{{ .PublishDate | time.Format ":date_medium" }}</small></p> + {{- end }} + </header> + {{- end }} + {{- end }} + + {{- block "main" . }} + {{- .Content }} + {{- end }} + + {{- with .Parent }} + <nav> + <p>Go back to <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>.</p> + </nav> + {{- end }} + </body> +</html> diff --git a/layouts/_default/list.html b/layouts/_default/list.html new file mode 100644 index 0000000..f8f44d1 --- /dev/null +++ b/layouts/_default/list.html @@ -0,0 +1,17 @@ +{{- define "main" }} +<main> + {{- .Content }} + {{- if .Pages }} + <ul> + {{ range .Pages }} + <li> + {{- if .LinkTitle }} + <p><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>.</p> + {{- end }} + {{ .Summary }} + </li> + {{ end }} + </ul> + {{- end }} +</main> +{{- end }} diff --git a/layouts/_default/single.html b/layouts/_default/single.html new file mode 100644 index 0000000..c023229 --- /dev/null +++ b/layouts/_default/single.html @@ -0,0 +1,6 @@ +{{- define "main" }} +{{/* + Yes, this is identical to baseof.html's definition. This template is still needed, in order for Hugo to actually generate single pages. +*/}} +{{- .Content }} +{{- end }} diff --git a/layouts/index.html b/layouts/index.html new file mode 100644 index 0000000..f9f48e1 --- /dev/null +++ b/layouts/index.html @@ -0,0 +1,17 @@ +{{- define "main" }} +<main> + {{- if .Pages }} + <ul> + {{ range .Pages }} + <li> + {{- if .LinkTitle }} + <p><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>.</p> + {{- end }} + {{ .Summary }} + </li> + {{ end }} + </ul> + {{- end }} + {{- .Content }} +</main> +{{- end }} diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index f04f135..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,13 +0,0 @@ -site_name: The Grimoire - -nav: - - index.md - - code/index.md - - nomic/index.md - -repo_url: https://gitlab.com/grimoire-ca/bliki/ - -markdown_extensions: - - toc: - permalink: true - - admonition diff --git a/tools/build b/tools/build index 5e25d51..49b2007 100755 --- a/tools/build +++ b/tools/build @@ -4,6 +4,6 @@ cd "$(dirname "$0")/.." ## tools/build ## -## Converts the content in docs/ into a deployable website in site/ +## Converts the content in content/ into a deployable website in public/ -exec mkdocs build +exec hugo --cleanDestinationDir diff --git a/tools/publish b/tools/publish index 9ee5d71..14a69ef 100755 --- a/tools/publish +++ b/tools/publish @@ -4,8 +4,13 @@ cd "$(dirname "$0")/.." ## tools/publish ## -## Publishes site/ to the S3 bucket hosting grimoire.ca +## Publishes public/ to the server hosting grimoire.ca -exec rsync -zav --delete --progress \ - site/ \ +exec rsync \ + --compress \ + --archive \ + --delete \ + --verbose \ + --progress \ + public/ \ admin@grimoire.ca:/srv/grimoire.ca/webroot/ |