fix(release): lightweight tags in the snap build, version fallback, man pages for help topics, draft the 1.0.0 changelog

Signed-off-by: bircni <bircni@icloud.com>

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [v1.0.0] - unreleased
+
+See [docs/migration-1.0.md](docs/migration-1.0.md) for the full list of changes and how to update scripts.
+
+* BREAKING
+  * Rebuild tea on Cobra with explicit, singular `noun verb` commands modeled on `gh` (#1126); plural groups and the old built-in aliases are gone, groups no longer run a default action, and `tea alias set` defines shortcuts
+  * Split the configuration into `config.yml` (preferences) and `hosts.yml` (instances and accounts); the old `config.yml` is not imported, archive it or set `TEA_CONFIG_DIR`
+  * Replace `tea login` with `tea auth` (`login`, `status`, `switch`, `logout`, `refresh`, `token`, `setup-git`); accounts are identified by instance URL and username, and credentials are stored in the OS keyring or in private files
+  * Replace `--login` with `--host`/`--user`, and change global and per-command short flags to follow `gh` (`-R` is `--repo`, `-L` is `--limit`, `-y` is `--yes`)
+  * Remove `--output` and `--fields` in favor of `--json` and `--jq`; commands that return no resource reject `--json`
+  * Use exit codes 0, 1, 2 (usage), 3 (canceled), 4 (authentication), 8 (pending checks) and 130 (interrupted); `tea api` exits 1 on a response outside 2xx
+  * Require Gitea 28 or newer; tea no longer probes the server version
+  * Remove `tea open`, basic-auth token creation, `GH_TOKEN` and the `GITEA_SERVER_*` variables, and the `--generate-shell-completion` protocol
+  * Change several commands to follow `gh`: `pr review` takes `--approve`, `--request-changes` or `--comment`, `pr checkout` names the local branch after the head branch, `label list` shows only the selected scope, and `notification` commands act on the whole inbox
+* FEATURES
+  * Add `tea auth setup-git` as a Git credential helper, and authenticate Git for clone, checkout and sync without one
+  * Add `--no-input`, `--yes`, `--cwd` and `--sudo` global flags, and `TEA_CONFIG_DIR`, `TEA_HOST`, `TEA_USER`, `TEA_REPO`, `TEA_EDITOR`, `TEA_PAGER` and `TEA_COLOR`
+  * Add `tea issue list --no-assignee`
+  * Add `tea help environment`, `tea help exit-codes` and `tea help formatting`
+* ENHANCEMENTS
+  * Render Markdown and tables for the terminal, and print plain tab-separated output when piped
+  * Load the interactive create form data concurrently and read the pull request template with one request
+  * Fix many correctness issues found in a review of every command group
+* MISC
+  * Add a services layer on the Gitea Go SDK (#1125) and a terminal output and forms package (#1124)
+  * Require Go 1.27
+
 ## [v0.13.0](https://gitea.com/gitea/tea/releases/tag/v0.13.0) - 2026-04-05
 
 * FEATURES

internal/app/man.go

@@ -40,10 +40,7 @@ func (a *application) manCommand() *cobra.Command {
 						return err
 					}
 					if len(args) == 0 {
-						for _, child := range page.Commands() {
+						for _, child := range ManualCommands(page) {
-							if child.Hidden {
-								continue
-							}
 							if err := render(child); err != nil {
 								return err
 							}
@@ -67,3 +64,15 @@ func ManualDate(getenv func(string) string) time.Time {
 	}
 	return time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)
 }
+
+// ManualCommands lists the subcommands that get a page in the manual: the available commands,
+// without the generated help command, and the help topics such as environment and exit-codes.
+func ManualCommands(page *cobra.Command) []*cobra.Command {
+	var children []*cobra.Command
+	for _, child := range page.Commands() {
+		if child.Annotations[topicAnnotation] != "" || (child.IsAvailableCommand() && !child.IsAdditionalHelpTopicCommand()) {
+			children = append(children, child)
+		}
+	}
+	return children
+}

internal/app/man_test.go

@@ -66,3 +66,12 @@ func TestCanceledManDoesNotPublishOutputFile(t *testing.T) {
 	require.True(t, os.IsNotExist(err))
 	require.Empty(t, out.String())
 }
+
+func TestManIncludesHelpTopicsButNotHelpCommands(t *testing.T) {
+	deps, out, _ := testDeps(t)
+	require.NoError(t, Execute(context.Background(), deps, []string{"man"}))
+	manual := out.String()
+	require.Contains(t, manual, `.TH "TEA-ENVIRONMENT"`)
+	require.Contains(t, manual, `.TH "TEA-EXIT-CODES"`)
+	require.NotContains(t, manual, `.TH "TEA-PR-HELP"`)
+}

internal/transport/client.go

@@ -111,7 +111,7 @@ type Client struct {
 }
 
 // UserAgent identifies tea to instances, proxies, and server logs.
-var UserAgent = "tea/" + version.Version + " (" + runtime.GOOS + "/" + runtime.GOARCH + ")"
+var UserAgent = "tea/" + version.Current() + " (" + runtime.GOOS + "/" + runtime.GOARCH + ")"
 
 type userAgentTransport struct{ base http.RoundTripper }
 

internal/transport/client_test.go

@@ -135,7 +135,7 @@ func TestTransportBoundsOnlySetupAndSendsUserAgent(t *testing.T) {
 		require.NoError(t, err)
 		require.NoError(t, response.Body.Close())
 	}
-	want := "tea/" + version.Version + " (" + runtime.GOOS + "/" + runtime.GOARCH + ")"
+	want := "tea/" + version.Current() + " (" + runtime.GOOS + "/" + runtime.GOARCH + ")"
 	require.Equal(t, []string{want, want}, agents)
 }
 

internal/version/version.go

@@ -36,13 +36,29 @@ func Format() string {
 	return format(Version, Tags, runtime.Version(), info)
 }
 
+// Current returns the version of this build: the ldflags stamp, else the module version recorded
+// by go install, else "development".
+func Current() string {
+	info, _ := debug.ReadBuildInfo()
+	return resolve(Version, info)
+}
+
+func resolve(version string, info *debug.BuildInfo) string {
+	// A build without a checkout (a source archive) stamps an empty version.
+	if version != "" && version != "development" {
+		return version
+	}
+	// go install gitea.dev/tea@v1.0.0 stamps the module version instead of the ldflags.
+	if info != nil && info.Main.Version != "" && info.Main.Version != "(devel)" {
+		return strings.TrimPrefix(info.Main.Version, "v")
+	}
+	return "development"
+}
+
 func format(version, tags, goVersion string, info *debug.BuildInfo) string {
+	version = resolve(version, info)
 	date := ""
 	if info != nil {
-		// go install gitea.dev/tea@v1.0.0 stamps the module version instead of the ldflags.
-		if version == "development" && info.Main.Version != "" && info.Main.Version != "(devel)" {
-			version = strings.TrimPrefix(info.Main.Version, "v")
-		}
 		for _, setting := range info.Settings {
 			if setting.Key != "vcs.time" {
 				continue

internal/version/version_test.go

@@ -28,3 +28,12 @@ func TestFormatDescribesTheBuild(t *testing.T) {
 		})
 	}
 }
+
+func TestResolveFallsBackWhenUnstamped(t *testing.T) {
+	installed := &debug.BuildInfo{Main: debug.Module{Version: "v1.0.1"}}
+	require.Equal(t, "1.0.1", resolve("development", installed))
+	require.Equal(t, "1.0.1", resolve("", installed))
+	require.Equal(t, "development", resolve("", nil))
+	require.Equal(t, "development", resolve("", &debug.BuildInfo{Main: debug.Module{Version: "(devel)"}}))
+	require.Equal(t, "1.0.0", resolve("1.0.0", installed))
+}

snap/snapcraft.yaml

@@ -30,7 +30,7 @@ parts:
       craftctl default
 
       git config --global --add safe.directory /root/parts/tea/src
-      last_committed_tag="$(git for-each-ref --sort=taggerdate --format '%(tag)' refs/tags | tail -n 1)"
+      last_committed_tag="$(git for-each-ref --sort=creatordate --format '%(refname:short)' refs/tags | tail -n 1)"
       last_released_tag="$(snap info gitea-tea | awk '$1 == "latest/candidate:" { print $2 }')"
       # If the latest tag from the upstream project has not been released to
       # stable, build that tag instead of main.
@@ -39,7 +39,7 @@ parts:
         git checkout "${last_committed_tag}"
       fi
 
-      version="$(git describe --always | sed -e 's/-/+git/;y/-/./')"
+      version="$(git describe --tags --always | sed -e 's/-/+git/;y/-/./')"
       [ -n "$(echo $version | grep "+git")" ] && grade=devel || grade=stable
       craftctl set version="$version"
       craftctl set grade="$grade"

tools/cli-docs/main.go

@@ -70,6 +70,24 @@ func generate(output string) error {
 	if err := doc.GenManTree(root, header, filepath.Join(output, "man")); err != nil {
 		return err
 	}
+	// Cobra skips the hidden help topics (environment, exit-codes, formatting); give them pages too.
+	for _, topic := range app.ManualCommands(root) {
+		if topic.Runnable() || topic.Annotations["tea.topic"] == "" {
+			continue
+		}
+		var page strings.Builder
+		if err := doc.GenMarkdownCustom(topic, &page, func(string) string { return "" }); err != nil {
+			return err
+		}
+		name := "tea_" + topic.Name() + ".md"
+		if err := os.WriteFile(filepath.Join(output, "reference", name), []byte(strings.TrimRight(page.String(), "\n")+"\n"), 0o644); err != nil {
+			return err
+		}
+		topicHeader := &doc.GenManHeader{Title: "TEA-" + strings.ToUpper(topic.Name()), Section: "1", Date: &date, Source: "Tea", Manual: "Tea Manual"}
+		if err := writeFile(filepath.Join(output, "man", "tea-"+topic.Name()+".1"), func(w io.Writer) error { return doc.GenMan(topic, topicHeader, w) }); err != nil {
+			return err
+		}
+	}
 	completions := []struct {
 		name  string
 		write func(io.Writer) error