From d4958732c8813e2dd821583e3457d125d3ba6266 Mon Sep 17 00:00:00 2001 From: Mechiel Lukkien Date: Tue, 26 Mar 2024 09:16:33 +0100 Subject: [PATCH] add more of a "getting started with building" to develop.txt based on #145 by lmeunier --- Makefile | 16 +++++++++++++--- README.md | 2 ++ develop.txt | 50 ++++++++++++++++++++++++++++++++++++++++---------- 3 files changed, 55 insertions(+), 13 deletions(-) diff --git a/Makefile b/Makefile index 18a8d55..7ce3a97 100644 --- a/Makefile +++ b/Makefile @@ -31,6 +31,10 @@ test-race: test-upgrade: build nice ./test-upgrade.sh +# needed for "check" target +install-staticcheck: + go install honnef.co/go/tools/cmd/staticcheck@v0.4.7 + check: CGO_ENABLED=0 go vet -tags integration CGO_ENABLED=0 go vet -tags website website/website.go @@ -45,6 +49,10 @@ check: staticcheck -tags errata rfc/errata.go staticcheck -tags xr rfc/xr.go +# needed for check-shadow +install-shadow: + go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@v0.19.0 + # having "err" shadowed is common, best to not have others check-shadow: go vet -vettool=$$(which shadow) ./... 2>&1 | grep -v '"err"' @@ -96,11 +104,11 @@ fmt: jswatch: bash -c 'while true; do inotifywait -q -e close_write *.ts webadmin/*.ts webaccount/*.ts webmail/*.ts; make frontend; done' -jsinstall: +install-js: -mkdir -p node_modules/.bin npm ci -jsinstall0: +install-js0: -mkdir -p node_modules/.bin npm install --save-dev --save-exact typescript@5.1.6 @@ -121,8 +129,10 @@ webaccount/account.js: lib.ts webaccount/api.ts webaccount/account.ts frontend: webadmin/admin.js webaccount/account.js webmail/webmail.js webmail/msg.js webmail/text.js +install-apidiff: + go install golang.org/x/exp/cmd/apidiff@v0.0.0-20231206192017-f3f8817b8deb + genapidiff: - # needs golang.org/x/exp/cmd/apidiff@v0.0.0-20231206192017-f3f8817b8deb installed ./apidiff.sh docker: diff --git a/README.md b/README.md index 7d679e6..10048f8 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,8 @@ for junk filtering and rate-limiting). # Future/development +See develop.txt for instructions/tips for developing on mox. + Mox will receive funding for essentially full-time continued work from August 2023 to August 2024 through NLnet/EU's NGI0 Entrust, see https://nlnet.nl/project/Mox/. diff --git a/develop.txt b/develop.txt index b680503..b241f70 100644 --- a/develop.txt +++ b/develop.txt @@ -1,5 +1,34 @@ This file has notes useful for mox developers. +# Building & testing + +For a full build, you'll need a recent Go compiler/toolchain and nodejs/npm for +the frontend. First install frontend dependencies (typescript) with "make +install-js". Then run "make build" to do a full build. Run "make test" to run +the test suite. With docker installed, you can run "make test-integration" to +start up a few mox instances, a dns server, a postfix instance, and send email +between them. + +The mox localserve command is a convenient way to test locally. Most of the +code paths are reachable/testable with mox localserve, but some use cases will +require a full setup. + +Before committing, run at least "make fmt" and "make check" (which requires +staticcheck, run "make install-staticcheck" once). Also run "make check-shadow" +and fix any shadowed variables other than "err" (which are filtered out, but +causes the command to always exit with an error code; run "make install-shadow" +once to install the shadow command). If you've updated RFC references, run +"make" in rfc/, it verifies the referenced files exist. + +When making changes to the public API of a package listed in +apidiff/packages.txt, run "make genapidiff" to update the list of changes in +the upcoming release (run "make install-apidiff" once to install the apidiff +command). + +New features may be worth mentioning on the website, see website/ and +instructions below. + + # Code style, guidelines, notes - Keep the same style as existing code. @@ -44,8 +73,8 @@ https://github.com/mjl-/sherpats/. The JavaScript that is generated from the TypeScript is included in the repository. This makes it available for inclusion in the binary, which is practical for users, and desirable given Go's reproducible builds. When -developing, run "make" to also build the frontend code. Run "make jsinstall" -once to install the TypeScript compiler into ./node_modules/. +developing, run "make" to also build the frontend code. Run "make +install-frontend" once to install the TypeScript compiler into ./node_modules/. There are no other external (runtime or devtime) frontend dependencies. A light-weight abstraction over the DOM is provided by ./lib.ts. A bit more @@ -60,18 +89,19 @@ managable. # Website The content of the public website at https://www.xmox.nl is in website/, as -markdown files. The website HTML is generated by website/website.go. The FAQ -is taken from README.md, the protocol support table is generated from -rfc/index.txt. The website is kept in this repository so a commit can change -both the implementation and the documentation on the website. Some of the info -in README.md is duplicated on the website, often more elaborate and possibly -with a slightly less technical audience. The website should also mostly be -readable through the markdown in the git repo. +markdown files. The website HTML is generated with "make genwebsite", which +writes to website/html/ (files not committed). The FAQ is taken from +README.md, the protocol support table is generated from rfc/index.txt. The +website is kept in this repository so a commit can change both the +implementation and the documentation on the website. Some of the info in +README.md is duplicated on the website, often more elaborate and possibly with +a slightly less technical audience. The website should also mostly be readable +through the markdown in the git repo. Large files (images/videos) are in https://github.com/mjl-/mox-website-files to keep the repository reasonably sized. -The public website serves the content from the "website" branch. After a +The public website may serve the content from the "website" branch. After a release release, the main branch (with latest development code and corresponding changes to the website about new features) is merged into the website branch. Commits to the website branch (e.g. for a news item, or any