Jason’s Web Site

Building

Prerequisites

• A Java 8 Runtime Environment
• Cargo*
• env (GNU coreutils)*
• GNU Bash*
• Go*
• npm*
• Python 3.8+
• Pipenv
• rustc

It’s possible that alternatives (like PyPy or FreeBSD’s env) will work, but they haven’t been tested.

*In general, I want this project and its build system to be platform neutral, but some of these aren’t platform neutral. The only reason these are dependencies is to build minify-html with a specific patch.

If you have Nix installed, then you can change directory to the root of this repo and run this command to start a shell that has all of the prerequisites installed:

nix-shell

Build and validate

1. Open a Bash terminal.
2. Change directory to the root of this repo.
3. Make sure that the submodule is ready. To do so, run:

   git submodule update --init --recursive

4. Run ./init-venv.sh
5. Run pipenv run python -m build_tool

The built site will be placed in the build folder.

After this has been done once, you just have to run pipenv run python -m build_tool again to rebuild the site.

You can run pipenv run python -m build_tool jasons-forge to build the static portion of Jason’s Software Forge’s site.

Hints for contributors

• Every file should declare its own copying information. See the comment at the top of COPYING.md for an example.
• Use tabs for indentation. The only exception to this rule is in YAML files because YAML requires spaces for indentation. In YAML files, use 4 spaces for indentation.
• The templates folders contains Jinja templates.
• Pass build.py the --help flag. You may find some of its options useful (like --scheme).

pre-commit

You can use pre-commit to automatically check your contributions. One of the hooks that this repo uses is Beautysh. Beautysh uses the poetry packaging tool. Unfortunately, it’s a bit of a hassle to get hooks that use poetry to work at the moment due to one or more upstream bugs. To get pre-commit to work with this repo, here’s what you need to do. Hopefully this process will become simpler overtime.

1. Build the site if you haven’t done so at least once already.
2. Open a Bash terminal.
3. Make sure that pre-commit is installed.
   1. Run pre-commit --version
   2. If it gives you an error, follow these instructions.
4. cd to the root of this repo.
5. Install the hook that’s affected by this problem. To do so, run

   SETUPTOOLS_USE_DISTUTILS=stdlib pre-commit install-hooks -c .pre-commit-config-problematic.yaml

6. Install pre-commit as a Git hook. To do so, run

   pre-commit install

At this point, whenever you run git commit, pre-commit will run a series of tests for the files that you modified.

There’s a few pre-commit hook failures that I’m OK with:

• Some Markdown files fail one of pre-commit’s hooks, but only because one line is too long. I’m OK with that line being too long.
• SPDX-FileContributor dates must end in the current year (see the comment at the top of the file as an example). Sometimes though, it’s correct for them not to (example: a file copied from another project).

When I run into an error that I’m OK with, I skip the failing hooks for that commit.

Copying

See COPYING.md.