From 6236717fdb9f622e73eba123653ed1043b1d8b66 Mon Sep 17 00:00:00 2001 From: Stefan Date: Sun, 29 Mar 2026 15:01:08 +0200 Subject: [PATCH] Refactor documentation for clarity and consistency, update test function naming convention --- AGENTS.md | 46 +++++++++++++++++++++++++++++--------- README.md | 20 ++++++++--------- docs/DEFINITION_OF_DONE.md | 13 +++++++++-- os_windows_test.go | 2 +- 4 files changed, 57 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 32fd1c9..6de3336 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,14 +1,20 @@ # AGENTS.md ## Purpose -This file defines the default working agreement for AI coding agents and contributors in this repository. + +This file defines the default working agreement for AI coding agents +and contributors in this repository. ## Documentation Language -Project language is English. All documentation, issues, pull requests, commit messages, and code comments should be written in English. + +Project language is English. All documentation, issues, pull requests, +commit messages, and code comments should be written in English. All newly created documentation in this project must be written in English. -All project documentation files must be stored under `docs/`, except `README.md` and `AGENTS.md`. +All project documentation files must be stored under `docs/`, +except `README.md` and `AGENTS.md`. ## Working Principles + 1. Keep changes minimal and focused on the requested task. 2. Preserve existing public APIs unless a breaking change is explicitly requested. 3. Prefer clear, maintainable code over clever shortcuts. @@ -16,22 +22,29 @@ All project documentation files must be stored under `docs/`, except `README.md` 5. Never add secrets, credentials, or tokens to the repository. ## Testing Expectations -1. Add or update tests for behavior changes. + +1. Add or update tests for behaviour changes. 2. Keep tests deterministic and fast. 3. Prefer table-driven tests where they improve readability. 4. Run relevant tests locally before finishing changes. -5. For Go projects, use `github.com/smartystreets/goconvey` as the standard test library. +5. For Go projects, use `github.com/smartystreets/goconvey` + as the standard test library. ## Build Artifacts and Reports + 1. Builder logs and generated reports must be created under `.build/`. 2. The `.build/` directory must be excluded from version control via `.gitignore`. ## Git and Script Standards + 1. Shell scripts (`*.sh`) must use LF line endings. -2. Shell scripts committed to the repository must be executable in Git index (mode `100755`). -3. When adding a new shell script, set execute permissions before commit: `git add --chmod=+x path/to/script.sh`. +2. Shell scripts committed to the repository must be executable + in Git index (mode `100755`). +3. When adding a new shell script, set execute permissions before commit: + `git add --chmod=+x path/to/script.sh`. ## Git Bash Execution Defaults + 1. Repository maintenance scripts are executed with Git Bash shell on Windows. 2. Default repository root is `~/git`. 3. The repository root can be overridden via `GO_GIT_ROOT`. @@ -40,11 +53,15 @@ All project documentation files must be stored under `docs/`, except `README.md` ## Definition of Done (DoD) -### Purpose -The Definition of Done defines the minimum quality bar for every completed change in this repository. +### DoD Purpose + +The Definition of Done defines the minimum quality bar +for every completed change in this repository. ### Mandatory Criteria + 1. Tests + - Every code change is covered by tests where applicable. - New functionality includes new tests. - Bug fixes include at least one regression test. @@ -52,31 +69,40 @@ The Definition of Done defines the minimum quality bar for every completed chang - Automated test coverage is at least 80%. 1. Functional documentation + - Implemented functionality is documented. - Public API-relevant changes are reflected in README and/or docs. 1. Documentation standards + - Documentation is written in English. - Documentation files are placed under `docs/`. - Exceptions: `README.md` and `AGENTS.md` remain at repository root. ### Technical Completion Criteria + 1. Build and test status + - The project builds successfully. - Relevant test commands run successfully. 1. No unresolved critical issues + - No new blocking errors are introduced. -- Known non-blocking warnings are acceptable only if unrelated to the change or documented. +- Known non-blocking warnings are acceptable only if unrelated + to the change or documented. 1. SonarQube status + - No SonarQube errors are present. 1. Documentation structure + - Links to moved or newly added docs are valid. - Documentation structure remains consistent with project rules. ### Review Checklist (Quick) + - [ ] Change is implemented and meets acceptance criteria. - [ ] Tests were added/updated and pass. - [ ] Go tests use `github.com/smartystreets/goconvey`. diff --git a/README.md b/README.md index 7077afc..1756147 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -
- # Go utility library +![yoorie.de logo](https://www.yoorie.de/img/favicon_32.png) + [![Build Status](https://drone.yoorie.de/api/badges/go-lib/util/status.svg)](https://drone.yoorie.de/go-lib/util) ## Project Description @@ -41,22 +41,20 @@ go get scm.yoorie.de/go-lib/util package main import ( - "fmt" + "fmt" - "scm.yoorie.de/go-lib/util" + "scm.yoorie.de/go-lib/util" ) func main() { - if util.FileExists("config.yaml") { - fmt.Println("config file found") - } + if util.FileExists("config.yaml") { + fmt.Println("config file found") + } - fmt.Println(util.JoiningSlash("/api", "v1", "users")) - fmt.Println(util.GetGlobalConfigurationFile("myapp", "config.yaml")) + fmt.Println(util.JoiningSlash("/api", "v1", "users")) + fmt.Println(util.GetGlobalConfigurationFile("myapp", "config.yaml")) } ``` --- Copyright © 2023 yoorie.de - - diff --git a/docs/DEFINITION_OF_DONE.md b/docs/DEFINITION_OF_DONE.md index a47d72f..1bdb9ee 100644 --- a/docs/DEFINITION_OF_DONE.md +++ b/docs/DEFINITION_OF_DONE.md @@ -2,11 +2,13 @@ ## Purpose -This Definition of Done defines the minimum quality bar for every completed change in this repository. +This Definition of Done defines the minimum quality bar +for every completed change in this repository. ## Mandatory Criteria 1. Tests + - Every code change is covered by tests where applicable. - New functionality includes new tests. - Bug fixes include at least one regression test. @@ -14,10 +16,12 @@ This Definition of Done defines the minimum quality bar for every completed chan - Automated test coverage is at least 80%. 1. Functional documentation + - Implemented functionality is documented. - Public API-relevant changes are reflected in README and/or docs. 1. Documentation standards + - Documentation is written in English. - Documentation files are placed under `docs/`. - Exceptions: `README.md` and `AGENTS.md` remain at repository root. @@ -25,17 +29,22 @@ This Definition of Done defines the minimum quality bar for every completed chan ## Technical Completion Criteria 1. Build and test status + - The project builds successfully. - Relevant test commands run successfully. 1. No unresolved critical issues + - No new blocking errors are introduced. -- Known non-blocking warnings are acceptable only if unrelated to the change or documented. +- Known non-blocking warnings are acceptable only if unrelated + to the change or documented. 1. SonarQube status + - No SonarQube errors are present. 1. Documentation links and structure + - Links to moved or newly added docs are valid. - Documentation structure remains consistent with project rules. diff --git a/os_windows_test.go b/os_windows_test.go index 6415230..34085ee 100644 --- a/os_windows_test.go +++ b/os_windows_test.go @@ -11,7 +11,7 @@ import ( "golang.org/x/sys/windows" ) -func TestIsSuperUser_SidAllocationError(t *testing.T) { +func TestIsSuperUserSidAllocationError(t *testing.T) { Convey("IsSuperUser should return false when SID allocation fails", t, func() { origAllocate := allocateAdminGroupSid origFatalf := fatalf