golem15/summercms
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(14.3-03): document summer new and the one-command start

Browse Source 
- installation: one-liner first, what the script does and its overrides,
  running the generated app, summer new without the script, then the
  examples/hello walkthrough; the obsolete known-issues callout is gone (D-18)
- go modules and workspaces: what summer new writes (relative replace,
  framework detection order, committed relative go.work, no root go.sum);
  plugin:add adds a relative go.work path
- console scaffolding: Creating an application with --framework, --no-plugin,
  --no-git, the files written, first commit and naming convention (D-01)
- console introduction, llms note in site.yaml, root README quick start
This commit is contained in:
Jakub Zych
2026-10-08 12:08:35 +02:00
parent 90582522c7
commit e0640220f2
6 changed files with 178 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/architecture/go-modules-and-workspaces.md
View File

@@ -1,6 +1,6 @@
---
title: Go modules and workspaces
description: Require the framework module, develop plugins as local modules in a Go workspace, list them in summer.yaml and fork a plugin with a replace directive.
description: Require the framework module, see what summer new writes, develop plugins in a Go workspace, list them in summer.yaml and fork a plugin.
section: architecture
order: 20
---
@@ -26,6 +26,47 @@ replace git.golem15.com/golem15/summercms => ../summercms.go
`summer make:plugin` copies this framework `replace` into the new plugin's `go.mod`, rewritten relative to the plugin directory, so the plugin builds against the same checkout.
## Applications created by summer new
`summer new acme` writes these files for you in `sm-acme-app`, next to the framework checkout. The application module is `git.golem15.com/golem15/sm-acme-app`, and its `go.mod` replaces the framework with a relative path, so the directory pair can move together or be cloned elsewhere:
```text
module git.golem15.com/golem15/sm-acme-app
go 1.27.0
toolchain go1.27.0
require git.golem15.com/golem15/summercms v0.0.0
replace git.golem15.com/golem15/summercms => ../summercms
```
The starter plugin `golem15.acme` is added through `summer plugin:add`, so the same `go.mod` also gets a `require` of `git.golem15.com/golem15/sm-acme-app/plugins/acme` and a `replace` pointing at `./plugins/acme`.
`summer new` picks the framework checkout in this order:
1. the path given with `--framework`, relative to the current directory or absolute; a wrong path is an error, not a reason to keep looking;
2. a sibling directory named `summercms`, then `summercms.go`;
3. the source tree the `summer` binary was built from, when it was built from a checkout without `-trimpath`.
Every candidate counts only when its `go.mod` declares the module `git.golem15.com/golem15/summercms`; the directory name alone is not enough. Without a match, `summer new` stops and asks for `--framework`.
The application also gets a `go.work` that is committed with it. It lists the application itself and, unless `--no-plugin` was given, the starter plugin, both as relative `use` paths:
```text
go 1.27.0
toolchain go1.27.0
use (
.
./plugins/acme
)
```
There is no `go.sum` in the application root: builds go through the workspace, and `go.work.sum`, which Go writes on the first build, is listed in `.gitignore`. The starter plugin keeps its own `go.mod` and `go.sum` like any other plugin module.
## The summer.yaml manifest
The manifest in the application root names the application module, the binary `summer build` writes to `bin/`, and the plugins in activation order:
@@ -48,7 +89,7 @@ A plugin you develop inside the application lives in `plugins/<name>` as its own
- it adds the plugin to `summer.yaml`;
- it adds a `require` and a `replace` pointing at the local directory to the application's `go.mod`;
- it adds the plugin directory to the nearest `go.work`, creating one in the application root when there is none.
- it adds the plugin directory to the nearest `go.work` as a path relative to that file, such as `./plugins/blog`, creating a `go.work` in the application root when there is none.
With a `go.work` in place, `go build`, `go test` and your editor see every local plugin module together. `summer build` uses the nearest `go.work` it finds; without one it builds in module mode.