This is an automated email from the ASF dual-hosted git repository.
fenbox pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/answer.git
The following commit(s) were added to refs/heads/main by this push:
new 9e6ca4a0 docs: add repository and design guidelines (#1678)
9e6ca4a0 is described below
commit 9e6ca4a01d2462491323dbe04cd14ec34303e503
Author: Fen <[email protected]>
AuthorDate: Thu Nov 19 15:26:21 2026 +0800
docs: add repository and design guidelines (#1678)
## Proposed Changes
- Add `AGENTS.md` with repository structure, development commands,
coding conventions, testing guidance, and commit/PR expectations.
- Add an English `DESIGN.md` following the design.md alpha
specification, documenting React Bootstrap as the design foundation and
the default primary color `#0033FF`.
- Document existing theme overrides, dark mode, layout conventions, and
component usage, with YAML design tokens and source references.
## Validation
- Checked commands and conventions against repository configuration and
source files.
- Confirmed `DESIGN.md` contains no Chinese text.
- `git diff --cached --check` passed before committing.
- Documentation-only changes; no application tests run.
---
AGENTS.md | 31 ++++++++++++++++++++
DESIGN.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 129 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..c2f36934
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,31 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Apache Answer combines a Go backend with a React/TypeScript frontend.
`cmd/answer` is the executable entry point; `internal/` contains controllers,
services, repositories, schemas, and migrations. Shared Go utilities live in
`pkg/`, and extension interfaces live in `plugin/`. Frontend pages, components,
stores, and API clients are under `ui/src/`; static assets are in `ui/public/`,
and production output is embedded from `ui/build/`. Translations live in
`i18n/`, configuration examples in [...]
+
+## Build, Test, and Development Commands
+
+Use Go 1.25+, Node.js matching `ui/package.json` (`^20.19.0 || >=22.12.0`),
and pnpm 9.7.0. `make lint` also requires Docker or Podman installed and
running for the ASF header formatter.
+
+- `make generate`: install generators, regenerate Go code/API documentation,
and tidy modules.
+- `make ui`: install frontend dependencies and build the UI.
+- `make build`: regenerate code and build the `answer` executable.
+- `./answer init -C ./data` then `./answer run -C ./data`: initialize and run
locally.
+- Before `cd ui && pnpm start` (Vite, port 3000), set
`REACT_APP_API_URL=http://localhost:8080/` in `ui/.env.development.local`,
matching your backend address. This overrides the checked-in private proxy
target; restart Vite after changes.
+- `make test`: run repository integration tests.
+- `go test ./...`: run the full Go test suite.
+- `make lint`: regenerate code, check ASF headers, and run golangci-lint.
+- `cd ui && pnpm lint`: run ESLint with automatic fixes; `pnpm prettier`
formats frontend sources.
+
+## Coding Style & Naming Conventions
+
+Format Go with `gofmt`; use tabs and conventional exported `PascalCase` names.
Follow existing snake_case Go filenames and package organization. Frontend code
uses two spaces, single quotes, trailing commas, and an 80-column Prettier
target. Use PascalCase component directories and follow neighboring files.
Respect `.editorconfig`, ESLint, and ASF license headers. Regenerate generated
files through tooling rather than editing them manually.
+
+## Testing Guidelines
+
+Use Go's `testing` package and existing Testify assertions. Name files
`*_test.go` and functions `TestXxx`. Add regression coverage for changed
behavior. Repository tests default to SQLite; MySQL/PostgreSQL variants use
`TEST_DB_DRIVER` and Docker. No fixed coverage threshold or frontend test
script is configured; verify UI changes with `pnpm build` and browser checks.
+
+## Commit & Pull Request Guidelines
+
+Follow history's conventional prefixes: `fix:`, `feat:`, `build:`, `test:`, or
`chore:`, with optional scope, such as `fix(security): enforce visibility`.
Keep commits focused. Follow the PR template: link the issue with `Fixes #...`
and describe proposed changes. Include validation results and screenshots for
visible UI changes. Review generated changes before committing; CI checks
linting and unexpected generated diffs.
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 00000000..91923698
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,98 @@
+---
+version: alpha
+name: Apache Answer
+description: A React Bootstrap interface for Q&A communities, branded through
the primary color.
+omitted:
+ - section: typography
+ reason: Inherits Bootstrap typography without separate brand typography
tokens.
+ - section: spacing
+ reason: Uses Bootstrap spacing utilities and existing page layouts without
a separate spacing scale.
+ - section: rounded
+ reason: Inherits default Bootstrap component radii.
+ - section: motion
+ reason: Inherits Bootstrap and React Bootstrap component transitions.
+---
+
+# Apache Answer Design System
+
+## Overview
+
+Apache Answer supports Q&A communities and knowledge sharing. Keep the
interface clear and practical, prioritizing readable questions, answers, and
actions.
+
+The foundation is **React Bootstrap 2.10.6 + Bootstrap 5.3.3** (currently
locked versions). Brand customization changes only the primary color. Component
structure, sizing, typography, radii, and interactions follow Bootstrap
defaults. Reuse existing domain styles and layouts without expanding them into
a separate component design system.
+
+Dependency sources: `@ui/package.json` and `@ui/pnpm-lock.yaml`. Global
stylesheet entry point: `@ui/src/index.scss`.
+
+## Colors
+
+The default brand primary is **Answer Blue / `#0033FF`**, used for primary
actions, links, selected states, and branded navigation. Success, warning,
danger, secondary actions, and neutrals retain Bootstrap semantic colors. Do
not turn every state blue.
+
+```yaml
+colors:
+ primary: "#0033FF"
+```
+
+This token represents the default theme. The site setting
`theme_config[theme].primary_color` can override the active primary color.
Design previews should reflect the target site's configuration.
+
+At build time, `@ui/src/common/_variable.scss` sets the default primary
through `$blue` before Bootstrap is imported. At runtime,
`@ui/src/components/CustomizeTheme/index.tsx` synchronizes primary colors,
links, buttons, pagination, selected items, and form focus states. Reuse this
mechanism to derive hover, active, focus, and disabled states instead of
introducing isolated color values.
+
+Light and dark modes use `data-bs-theme`. Bootstrap semantic variables and
`@ui/src/common/color.scss` adapt surfaces, text, and borders. Dark mode links
use lighter primary shades derived by the existing theme logic. Avoid hardcoded
light backgrounds in components.
+
+## Typography
+
+Use Bootstrap's default system font stack, sizes, weights, and line heights.
Establish hierarchy with semantic headings, body text, and existing utilities
such as `small`. Keep the existing typography scale and system fonts. Project
utilities such as `.small` and `.fs-12` follow their global stylesheet
definitions.
+
+Long questions, answers, and code should wrap or scroll locally without
overflowing the page. Preserve semantic headings, form labels, and body
structure.
+
+## Layout
+
+Use Bootstrap responsive containers, grids, breakpoints, and spacing
utilities. Reuse neighboring page layouts first. Pages typically combine
navigation, main content, and an optional sidebar. Stack content naturally on
narrow screens and keep primary actions accessible.
+
+The existing sidebar layout is defined in `@ui/src/common/sideNavLayout.scss`:
`.main-mx-with` has a maximum width of `1072px`; `.page-right-side` has a
desktop width of `300px` and becomes full width below `1199.9px`. Inherit these
values when using that layout, rather than imposing them on every page.
+
+## Elevation & Depth
+
+Use Bootstrap borders, surface layers, and default overlay styles to
distinguish regions. Preserve the existing navigation shadow. Keep ordinary
content areas free of additional decorative shadows. Dropdowns, tooltips, and
modals follow component defaults for stacking and positioning.
+
+## Shapes
+
+Buttons, inputs, cards, and modals retain Bootstrap default radii and borders.
Domain elements such as avatars and tags reuse their existing component shapes.
Do not apply a universal pill or square treatment.
+
+## Motion & Micro-interaction
+
+Use React Bootstrap's built-in collapse, fade, and component state feedback.
Preserve default transition timing and honor `prefers-reduced-motion`. Avoid
decorative looping animation. Asynchronous actions should communicate loading
and prevent duplicate submission.
+
+## Voice & Content Strategy
+
+Write direct, friendly copy with clear action names and consistent Q&A
terminology. Reuse existing translation keys in `i18n/`. Add new copy through
the internationalization workflow rather than hardcoding a single language in
components.
+
+Action labels describe outcomes, such as “Post question” and “Save changes.”
Empty states explain what is missing and suggest a next step. Errors explain
the failure and an actionable remedy. Dates, numbers, and capitalization follow
the active locale and neighboring interfaces.
+
+## Components
+
+Prefer components exported by `react-bootstrap` and reuse existing domain
wrappers in `ui/src/components/`.
+
+- **Buttons:** Use `Button variant="primary"` for primary actions. Use
existing secondary, outline, or link variants for secondary actions. Preserve
danger semantics for destructive actions.
+- **Forms:** Use standard `Form`, `Form.Control`, and `Form.Select`
components. Keep labels, help text, validation messages, and visible focus.
Checked states and focus colors follow the theme.
+- **Navigation and pagination:** Reuse Nav, Navbar, Dropdown, and Pagination.
Selected states follow primary; sizing and keyboard behavior follow component
defaults.
+- **Content and feedback:** Reuse Card, ListGroup, Alert, Modal, and Tooltip.
Question tags retain existing tag components and `.badge-tag` styling.
+- **Icons:** Use the project's existing Bootstrap Icons. Give icon buttons
accessible names.
+
+These tokens describe only the brand color mapping for default primary
buttons. Bootstrap supplies other properties, and the existing theme
implementation derives interaction states.
+
+```yaml
+components:
+ button-primary:
+ backgroundColor: "{colors.primary}"
+ button-outline-primary:
+ textColor: "{colors.primary}"
+```
+
+## Do's and Don'ts
+
+- Prefer component props, Bootstrap utilities, and semantic CSS variables.
+- Maintain primary at the theme entry points; avoid repeating hardcoded
`#0033FF` in domain components.
+- Preserve hover, focus, active, disabled, loading, and validation states.
+- Check light mode, dark mode, narrow screens, and keyboard interaction. Keep
text, icons, and focus indicators clearly visible.
+- Keep the existing font, radius, shadow, spacing, and button systems.
+- Preserve danger, success, and warning semantics. Communicate status through
more than color alone.