From fcef42e339e12e09ea4e4490e0c4b166fe4c0d16 Mon Sep 17 00:00:00 2001 From: andreacfromtheapp <3269984+andreacfromtheapp@users.noreply.github.com> Date: Sat, 25 Oct 2025 09:36:34 +0200 Subject: [PATCH 1/2] feat!: migrating from Makefile to Just MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apologies about the unrequested change. Opening this as **demo** one of some QoL improvement suggestions for @nellshamrell . It's up to you all do decide :) ## Migrate from Makefile to Justfile This PR converts the existing Makefile to a Justfile for improved developer experience and modern tooling. ### Changes Made **Core Migration:** - Converted all Make targets to Just recipes with equivalent functionality - Updated syntax from Make to Just format (removed `#!/bin/sh`, updated variable references) - Replaced `$(shell pwd)` with `{{justfile_directory()}}` for path resolution - **All original functionalities preserved** - no behavioral changes to existing workflows **Enhanced User Experience:** - Added `help` recipe that displays all available commands with descriptions - Improved recipe descriptions for better clarity in help output - Added project title and essential user information **Container Runtime:** - Renamed `build` → `docker-build` for explicit Docker usage - Fixed directory creation before container execution to prevent volume mount errors **Documentation Updates:** - Updated README.md to reference [Just](https://just.systems/) instead of Make - Changed all command examples from `make` to `just` ### Testing - **Verified `just website` works end-to-end**: Successfully generated 625 articles and hosted local server on port 8000 - **Verified `just email` works end-to-end**: Successfully generated email template `622-2025-10-22-email.html` - **Verified individual email commands**: Both `just generate-email` and `just optimize-email` work correctly as standalone operations - **Verified clean operations**: Both `just clean-website` and `just clean-email` work correctly - All container operations function correctly with the new justfile syntax ### Usage ```bash # Show all available commands just help # Main workflows (same as before) just website # Generate and host website locally just email # Generate and optimize email template just copy-website-contents # Sync to github.io repo # Container build just docker-build # Build Docker image ``` ### Benefits - **Better UX**: Built-in help system with clear command descriptions - **Modern tooling**: Just provides better syntax and features than Make - **Improved reliability**: Fixed volume mounting issues - **Full compatibility**: All existing workflows remain unchanged All existing workflows remain unchanged - users can simply replace `make` with `just` in their commands. Signed-off-by: andreacfromtheapp <3269984+andreacfromtheapp@users.noreply.github.com> --- README.md | 6 +-- publishing/Dockerfile | 4 +- publishing/{Makefile => justfile} | 63 ++++++++++++++++++++----------- 3 files changed, 45 insertions(+), 28 deletions(-) rename publishing/{Makefile => justfile} (60%) mode change 100755 => 100644 diff --git a/README.md b/README.md index 33f33c0de..58422b451 100644 --- a/README.md +++ b/README.md @@ -177,7 +177,7 @@ Use the included `new_contribs.sh` script: ## Building To ensure consistency across development setups, we use a [Docker](https://www.docker.com) container-based -workflow for building the website and email newsletter. Similarly, we use a `makefile` to ensure you have Docker installed on your system if +workflow for building the website and email newsletter. Similarly, we use [Just](https://just.systems/) to ensure you have Docker installed on your system if you intend to build the website or email newsletter. ### Building the website @@ -196,7 +196,7 @@ cd publishing - Run the Docker build and website local-host command: ```sh -make website +just website ``` - View the website locally at default @@ -226,7 +226,7 @@ cd publishing - Run the Docker build and website local-host command: ```sh -make email +just email ``` - View the email newsletter formatting of specific posts at diff --git a/publishing/Dockerfile b/publishing/Dockerfile index 44894fdf9..fca15d29f 100644 --- a/publishing/Dockerfile +++ b/publishing/Dockerfile @@ -1,6 +1,6 @@ FROM python:3.8.16-slim -# Must run from base `twir` directory... Makefile takes care of this. +# Must run from base `twir` directory... justfile takes care of this. WORKDIR /usr/twir # Install deps and set locales @@ -35,7 +35,7 @@ COPY plugins plugins COPY themes themes COPY pelicanconf.py pelicanconf.py -# make build && make generate-website && make host-website needs these scripts +# just website && just email needs these scripts COPY publishing/*.sh . RUN chmod +x *.sh diff --git a/publishing/Makefile b/publishing/justfile old mode 100755 new mode 100644 similarity index 60% rename from publishing/Makefile rename to publishing/justfile index 72d9cd059..030228194 --- a/publishing/Makefile +++ b/publishing/justfile @@ -1,12 +1,15 @@ -#!/bin/sh - +# This Week in Rust - Publishing Tools # TODO: Make sure running from latest "main" branch commit +# Show available recipes +help: + @just --list + # Typical flows: # -# 1. `make website` +# 1. `just website` # The first workflow will generate the desired website, landing -# the end contents in the local "output-website/" directory. This is the +# the end contents in the local "output-website/" directory. This is the # equivalent of running `pelican --delete-output-directory content` # from a properly instantantiated environment. # @@ -16,62 +19,76 @@ # # Output: `output-website/` # -# 2. `make copy-website-contents` +# 2. `just copy-website-contents` # This workflow will sync the `output-website/` directory from above, and sync # it with the directory passed to it. Used for syncing state with # this-week-in-rust.github.io repo. # -# 3. `make email` +# 3. `just email` # This workflow will generate the desired email template, landing -# the end contents in the local "email/" directory. This is the +# the end contents in the local "email/" directory. This is the # equivalent of running `USE_EMAIL_THEME=1 pelican --delete-output-directory content` # from a properly instantantiated environment, and running # `juice --web-resources-images false /juice/in.html /juice/out.html` on the latest content post. -# +# # $ build clean generate-email optimize-email # # Output: `email/----email.html` # +# Generate and host website locally website: generate-website host-website + +# Copy website contents to this-week-in-rust.github.io repo copy-website-contents: - @./copy_website_content_to_repo.sh + ./copy_website_content_to_repo.sh + +# Generate and optimize email template email: generate-email optimize-email -build: +# Build Docker image +docker-build: cd .. && docker build -t twir -f publishing/Dockerfile . && cd - +# Clean website output directories clean-website: - @rm -rf output/ && rm -rf output-website/ && rm -rf juice/ + rm -rf output/ output-website/ juice/ + +# Clean email output directories clean-email: - @rm -rf output/ && rm -rf output-email-format/ && rm -rf email/ && rm -rf juice/ + rm -rf output/ output-email-format/ email/ juice/ -generate-website: build clean-website +# Generate website content +generate-website: docker-build clean-website @echo "Generating website..." - @docker run -it \ - -v $(shell pwd)/output-website:/usr/twir/output \ - twir:latest + docker run -it \ + -v {{justfile_directory()}}/output-website:/usr/twir/output \ + twir:latest @echo "Finished generating website." +# Host website locally on port 8000 host-website: @echo "Hosting website..." - @docker run -it \ + docker run -it \ -p 8000:8000 \ - -v $(shell pwd)/output-website:/usr/twir/output:ro \ + -v {{justfile_directory()}}/output-website:/usr/twir/output:ro \ -it \ twir:latest \ bash run_server.sh @echo "Finished hosting website." @echo "" - @echo "To sync contents with your local 'this-week-in-rust.github.io' repo, run \033[1;33m'make copy-website-contents'\033[0m" + @echo "To sync contents with your local 'this-week-in-rust.github.io' repo, run 'just copy-website-contents'" -generate-email: build clean-email +# Generate email content +generate-email: docker-build clean-email @echo "Generating email..." - @docker run -it \ + mkdir -p output-email-format + docker run -it \ -e USE_EMAIL_THEME=1 \ - -v $(shell pwd)/output-email-format:/usr/twir/output \ + -v {{justfile_directory()}}/output-email-format:/usr/twir/output \ twir:latest +# Optimize email HTML for delivery optimize-email: @echo "Generating optimized email..." - @OUTPUT_PREFIX=output-email-format ./create_optimized_email.sh + OUTPUT_PREFIX=output-email-format ./create_optimized_email.sh From 5273ee18d38f985b5e1cfdeacb86f59c5ab0aa29 Mon Sep 17 00:00:00 2001 From: andreacfromtheapp <3269984+andreacfromtheapp@users.noreply.github.com> Date: Fri, 31 Oct 2025 13:23:39 +0100 Subject: [PATCH 2/2] docs: add Just install recommendation Signed-off-by: andreacfromtheapp <3269984+andreacfromtheapp@users.noreply.github.com> --- README.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 45f2acd4d..04f7d7053 100644 --- a/README.md +++ b/README.md @@ -187,9 +187,21 @@ Use the included `new_contribs.sh` script: ## Building -To ensure consistency across development setups, we use a [Docker](https://www.docker.com) container-based -workflow for building the website and email newsletter. Similarly, we use [Just](https://just.systems/) to ensure you have Docker installed on your system if -you intend to build the website or email newsletter. +To ensure consistency across development setups, we use a +[Docker](https://www.docker.com) container-based workflow for building the +website and email newsletter. Similarly, we use [Just](https://just.systems/) to +ensure you have Docker installed on your system if you intend to build the +website or email newsletter. + +### Install Just + +To install Just you have +[many options](https://just.systems/man/en/packages.html); we recommend using +Cargo: + +```sh +cargo install just +``` ### Building the website