archivistagd

A tool to facilitate documenting and analyzing game development processes.

Features

Features are being defined on the current project board, but some ideas can be found on the work-in-progress design notes. There is also a devlog folder with notes.

Installation

You need to have Node.js (version 16.13.0 or up), NPM (8.1.4 or up) and Git installed on your computer.

Mac OS

For MacOS users, it might be a good idea to check this resource on permission issues when installing global CLI tools. Then, before following the steps above, install Node and NPM using the nvm tool. This helps with permissions and proper versioning for npm. After that, the steps for installation and setup are the same.

For now, it might be better to run the tool as a local installation:

1. Download this repository;
2. Open a terminal window within its root folder;
3. Run the command npm install;

This way, the tool is installed locally. To run the tool, use node index.js and then the parameters and info described on the How to Use section. The command node index.js --help on the root folder should show usage instructions. Even if the tool is running from the folder where you installed it, it can generate websites in different locations on your computer, by passing an absolute path to the --output parameter.

Windows

1. Download this repository;
2. Open a terminal window within its root folder;
3. Run the command npm install;
4. Run the command npm link;

You should now have the archivistagd command available on your terminal on any folder you open it on. To check if the installation went well, open a new terminal and run archivistagd --help. It should output usage instructions.

How to use

Note to Mac users: for now, substitute archivistagd in the instructions below for node index.js.

The tool fetches a dev repo from GitHub (public repositories only, for now), clones it locally, and then generates a website (stored in a local folder) based on its Git log information. As an example, if I want to run it for my repo enricllagostera/sample_webgame_repo and save the website on a dist subfolder, I can run:

> archivistagd run --repo enricllagostera/sample_webgame_repo --output dist

info Running archivistagd for enricllagostera/sample_webgame_repo...
[11ty] Copied 1 file / Wrote 11 files in 0.15 seconds (13.6ms each, v1.0.0)
info Website generated and stored at: D:\arquivo_sinc\repos_geral\archivistagd\dist

If I want to visualize the generated website right away, I can pass in the --serve option:

> archivistagd run --repo enricllagostera/sample_webgame_repo --output dist

info Running archivistagd for enricllagostera/sample_webgame_repo...
[11ty] Copied 1 file / Wrote 11 files in 0.16 seconds (14.5ms each, v1.0.0)
info Website generated and stored at: D:\arquivo_sinc\repos_geral\archivistagd\dist
info Serving at: http://localhost:8080. Press Ctrl+C to stop.

Adding notes to a commit

Sometimes, commit logs can be limiting to use for writing more detailed or longer notes. Other times, they are used for specific tools and processes, like generating changelogs.

archivistagd lets you add notes to any specific commit page through note files. This is done in two ways: annotations and devlogs.

Devlogs

Devlogs are Markdown files loaded from a folder in the source gamedev repository. The folder is loaded from the latest commit on the gamedev repo. Each note file in the folder is added to the commit page it references in its metadata. Here is an example of a devlog note stored in a my_notes folder:

// my_notes/an-example-devlog.md
---
title: An example devlog note
author: CookieMonster
commitHash: 4a559630d01445a55c93044a541ef2f9e79981cc
creationDate: 2022-02-11
---

# A header for my devlog note

The part between dashes on the top of the file is the metadata (on YAML frontmatter format). This down here is the content of my note, which will be displayed in my commit with the hash specified in the metadata `commitHash` field.

The folder devlogs is the default location that archivistagd will look for devlog notes on the dev repo and add to the generated website. You can use the --devlogs/-d option to specify a different folder. So, in order for archivistagd to load the above example note (stored in a my_notes folder), I'd need to run the command with that option:

> archivistagd run --repo enricllagostera/sample_webgame_repo --output dist -d my_notes

Annotations

Annotations are Markdown files (.md extension) stored in a folder in the computer you are running archivistagd on. They need to include some metadata to connect the note to a commit. Here is an example, stored in an annotations folder in the same directory I'm running archivistagd on:

// annotations/my-example-annotation.md
---
title: An example annotation note
author: Enric
commitHash: 4a559630d01445a55c93044a541ef2f9e79981cc
creationDate: 2022-02-09
---

That part between dashes on the top of the file is the metadata. This down here is the content of my note, which will be displayed in my commit with the hash specified in the metadata `commitHash` field.

The folder annotations is the default location that archivistagd will look for annotations to add to the generated website. You can use the --annotations/-a option to specify a different folder, similarly to the devlogs example above.

Playable versions / builds

If the gamedev project is playable on the browser, you can set up a link to a playable build for each commit page. This is done by setting the --build option on the tool to the relevant folder's name in the dev repo. By default, no playable builds will be included. Here is an example for a project with a build sub-directory containing a browser based version of the game:

> archivistagd run --repo enricllagostera/sample_webgame_repo --output dist -b build

Another option, if the gamedev project is not playable on the browser, is to include a .zip file within the dev repo build folder. When clicking the link, the website user will then download the compressed file with the game executables.

Parameters

Below is a list of all the command-line options currently supported by the archivistagd run command. You access that list by executing archivistagd help run.

| Option | Description | | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | | -r, --repo | (required) GitHub repository ('user/name') with the source gamedev project (e.g. 11ty/eleventy) | | -o, --output | (required) local folder where to output the generated website | | -p, --url-prefix | adds a prefix to root-based paths (e.g. 'index.html') (default: "/") | | -a, --annotations | local folder with annotation files (default: "annotations") | | -d, --devlogs | folder in the dev repo with devlog files (default: "devlogs") | | -b, --build | folder in the dev repo with a playable build (default: "") | | -bz, --build-as-zip | creates a downloadable ZIP file with contents of playable build folder (defined via -b option) (default: false) | | -t, --temp | temp folder for tool downloads and data (default: "_temp") | | -c, --clear-temp | clear temp folders before generation | | -s, --serve | run a local server after generation | | -v, --verbose | set logging level to verbose | | -q, --quiet | set logging level to silent | | -ih, --ignore-with-hashes <hashes...> | specify commit hashes to filter out (default: []) | | -is, --ignore-with-subject <patterns...> | specify subject patterns to filter out (default: []) | | -h, --help | display help for command | | -V, --version | output the version number |

Loading parameters from a configuration file

You can also configure and run archivistagd using a different method. Loading the parameters from a config file facilitates setting up a repeatable build process and consistent execution. By using the command archivistagd from-config-file <config-file.json>, the tool will load the options above from a JSON file. If no config file is specified, the tool expects a default .archivistagd.json at the execution folder.

As an example, using the config file below is equivalent to running archivistagd run --repo enricllagostera/sample_webgame_repo --output dist -is ^Merge ^docs: -b build -s.

/* .archivistagd.json at the execution root folder (e.g. c:/my_folder/) */
{
  "repo": "enricllagostera/sample_webgame_repo",
  "output": "dist",
  "build": "build",
  "serve": "true",
  "ignoreWithSubject": ["^Merge", "^docs:"]
}

Executing archivistagd from-config-file at my c:/my_folder will result in:

PS c:/my_folder> archivistagd from-config-file

info ARCH Loading configs from .archivistagd.json...
info ARCH Running archivistagd for enricllagostera/sample_webgame_repo...
info ARCH Serving at: http://localhost:8080. Press Ctrl+C to stop.