Skip to content

ai: update knowledge base to new structure - #347

Closed
upils wants to merge 1 commit into
canonical:mainfrom
upils:overhaul-kb
Closed

upils wants to merge 1 commit into
canonical:mainfrom
upils:overhaul-kb

Conversation

@upils

@upils upils commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator
  • Have you signed the CLA?

@upils upils added the Simple Nice for a quick look on a minute or two label Nov 4, 2026

@lczyk lczyk left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm ( sans the one obvious contradiction with what chisel is supposed to to in the first place 😅 )

Comment thread .kb/repo-overview.md

## §2 - Provider independence

Chisel's operation and logic, including validation, must not rely on package contents or on information from package providers (currently the archive, in the future the bin store). Do as much as possible without fetching from package providers, so that operations stay fast and can work without network access.

@lczyk lczyk Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Chisel's operation and logic (...) must not rely on package contents or on information from (...) the archive". are we changing chisel in a way in which i was not aware of? 😄 more seriously, the previous workding was better imo: "as independent as practical from incidental package archive contents". as written it sounds like its going very strongly against the literal thing chisel is supposed to do.

also, leave bin store out until it exists? no strong opinions on that one though tbh.

Comment thread .kb/repo-overview.md

## Compatibility guidance

When introducing a new feature or fixing a bug, consider both backward and forward compatibility: new behavior must keep working with previous Chisel releases, and parsing of release YAML files must accept or reject values so that future format evolutions remain possible.

@lczyk lczyk Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reads a bit weird. how about something like "new versions of chisel must be able to keep reading old releases, and, where possible, release format changes stay parseable by older chisel versions."

edit: i mean the "new behavior must keep working with previous Chisel releases" bit
edit2: it pains me to write "behavior" but i've begrudgingly accept that US english is the standard... (🇬🇧)

@niemeyer niemeyer left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can actually drop most of the content, to be honest.

Some more details below:

Comment thread .kb/repo-overview.md
- `.golangci.yaml` - golangci-lint configuration.
- `README.md` - Project readme.
- `SECURITY.md` - Security policy.
- `LICENSE` - Project license.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's please avoid such listings, unless they are really adding value. Pretty much everything in the list at the moment is obvious from context at the moment.

Comment thread .kb/repo-overview.md
- `go.mod` - Go module definition.
- `go.sum` - Go dependency checksums.
- `spread.yaml` - Spread test configuration.
- `workshop.yaml` - Workshop configuration.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As an aside, this should go to a dotted file.

Comment thread .kb/repo-overview.md
@@ -0,0 +1,48 @@
# Preface

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My vote is to drop this entire file for now. It's not pulling its weight at the moment.

@@ -1,14 +1,36 @@
# Preface

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My vote is to drop this one as well. This is an unrelated collection of low-value ideas.

@@ -1,14 +1,17 @@
# Preface

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same.

@@ -1,18 +1,28 @@
# Preface

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same.. those files look like directory listings.

## License check

- When changing these packages or their dependencies, run `go run .github/scripts/external-packages-license-check.go` to verify the Apache-2.0 license boundary.
When changing these packages or their dependencies, run `go run .github/scripts/external-packages-license-check.go` to verify the license boundary.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems strange to ask the bot to be doing this every time it touches a file. This should probably be going to something like hacking.md next to other conventions that we follow, without asking for the action to be repeated on every change. If we want to have such a per-change action, it should be a single repository-wide static check, and then we don't need to tell what it is doing because if it fails it will say so.

@@ -1,13 +1,23 @@
# Preface

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one might stay, in the hope it grows to something useful. But let's rename it to snap-package.md, and drop the directory listing at the bottom.

# Directory
## §2 - Spread runner

Integration tests must be run with `spread`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's now a great law either. Sorry for nitpicking all over this, but I hadn't realized these files were so shallow.


## Running the suite

Tests are not run with `go test`. Each test scenario is a subdirectory containing a `task.yaml` with shell-based assertions, and requires no `//go:build` directives. Spread compiles and provisions the `chisel` binary as part of the test environment setup defined in `spread.yaml` at the repository root.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, let's just drop this file as well and bring it back later. This is not only of low value, but it's actively damaging by saying things like "tests aren't run with go test" with little context.

We can easily bring back something more substantial when we get into it.

@cooper-campbell cooper-campbell mentioned this pull request Nov 17, 2026
1 task done
@niemeyer

Copy link
Copy Markdown
Contributor

Superseded by #357.

@niemeyer niemeyer closed this Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Simple Nice for a quick look on a minute or two

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants