docs: add architecture overview and golangci-lint tooling - #1359
Open
Tatsinnit wants to merge 2 commits into
Open
docs: add architecture overview and golangci-lint tooling#1359Tatsinnit wants to merge 2 commits into
Tatsinnit wants to merge 2 commits into
Conversation
Add ARCHITECTURE.md documenting the codebase map, package layout, core sign/verify workflows, trust model, and developer workflow, linked from README.md and building.md. Add golangci-lint tooling: a conservative .golangci.yml adopted incrementally via new-from-rev, a 'lint' Makefile target, and a CI lint step (with fetch-depth: 0 so new-from-rev gating has git history). Signed-off-by: Tatsat Mishra <tamishra@microsoft.com>
Tatsinnit
requested review from
NiazFK,
gokarnm,
priteshbandi,
rgnote,
shizhMSFT,
toddysm,
vaninrao10 and
yizha1
as code owners
August 2, 2026 03:51
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1359 +/- ##
=======================================
Coverage 79.09% 79.09%
=======================================
Files 68 68
Lines 3076 3076
=======================================
Hits 2433 2433
Misses 436 436
Partials 207 207 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR adds an architecture overview document and introduces additive Go lint tooling/CI wiring to improve contributor onboarding and maintain code quality without enforcing the existing lint backlog.
Changes:
- Add
ARCHITECTURE.mdand link it fromREADME.mdandbuilding.md. - Add a
make linttarget and a golangci-lint v2 configuration. - Add a golangci-lint GitHub Actions step and adjust checkout depth for new-issues gating.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Adds a top-level link to the new architecture overview document. |
Makefile |
Introduces a lint target for running golangci-lint locally. |
building.md |
Links to ARCHITECTURE.md for codebase structure context. |
ARCHITECTURE.md |
New architecture and workflow documentation for the codebase. |
.golangci.yml |
Adds golangci-lint v2 configuration intended for incremental adoption. |
.github/workflows/build.yml |
Adds CI lint step and ensures git history is available for new-issues gating. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
new-from-rev: HEAD compares the tree against itself, producing an empty diff so no PR-introduced issues are ever reported. Switch to new-from-merge-base: origin/main so lint issues introduced by a PR are caught while the pre-existing backlog stays unenforced. Update the build.yml checkout comment and ARCHITECTURE.md to match. Signed-off-by: Tatsat Mishra <tamishra@microsoft.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This contribution is scoped for a minor update and possible latter minor release — it contains no source code, CLI, dependency, or Go-version changes, only documentation and additive developer/CI tooling.
Documentation
ARCHITECTURE.md— a map of the codebase: high-level architecture, package layout (cmd/notation,cmd/notation/internal,internal), core sign/verify workflows, trust model, developer workflow, and improvement opportunities.ARCHITECTURE.mdfromREADME.md(Development and Contributing) andbuilding.md.Developer / CI tooling (additive, non-breaking)
.golangci.yml(golangci-lint v2) with a conservative linter set. Adopted incrementally vianew-from-rev: HEAD, so only newly introduced issues fail CI — the existing backlog is not enforced.make linttarget.build.yml(golangci-lint-action v8, lint v2.5.0), and setfetch-depth: 0on checkout sonew-from-revgating has the git history it needs.Why it is safe for a minor release
cmd/orinternal/— no behavior, API, or CLI-flag changes.go.mod/dependency or Go toolchain changes.new-from-rev), so it cannot fail on the pre-existing backlog.Signed commits ✅