add more of a "getting started with building" to develop.txt

based on #145 by lmeunier
This commit is contained in:
Mechiel Lukkien
2024-03-26 09:16:33 +01:00
parent 40ade995a5
commit d4958732c8
3 changed files with 55 additions and 13 deletions

View File

@ -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