Skip to content

Add a funding subpackage that reads FUNDING.yml - #195

Open
paoValle wants to merge 1 commit into
git-pkgs:mainfrom
paoValle:feat/funding-discovery
Open

paoValle wants to merge 1 commit into
git-pkgs:mainfrom
paoValle:feat/funding-discovery

Conversation

@paoValle

Copy link
Copy Markdown

Adds the funding subpackage from the issue: Discover walks where GitHub looks for a
FUNDING.yml — .github/, the root, docs/, then the owner's .github repository — through
FileService, and Parse reads the same file from bytes for a caller that already has it.

Details worth knowing:

  • Discovery stops at the first file that exists, even when it declares nothing: existence, not
    content, decides which file GitHub reads.
  • The owner's .github repository is read from its own default branch — a tag or branch name from
    the repository being asked about does not exist there.
  • ErrNotFound and ErrNotSupported are both "nothing to read" (Tangled and Bitbucket answer
    ErrNotSupported for every Files().Get); any other error is returned wrapped.
  • The parser covers the flat subset GitHub accepts — scalars, quoted values, inline and block
    lists, comments, a leading BOM, a --- marker, CRLF — and ignores unknown keys so a file using a
    platform added later still parses.

Discovery is covered with a mocked FileService (the location order, the ref it sends, the error
cases); the parser has table tests for the shapes above and for the four it rejects.

go build ./..., go vet ./..., golangci-lint run ./funding/ (0 issues) and go test ./funding/
are clean. Four internal/cli tests fail on this machine both with and without the change: they
resolve the git remote before parsing the argument, and this clone's remote is an SSH alias.

Closes #174

Dependency funding tools need the donation links for a repository they have
already resolved. GitHub keeps them in FUNDING.yml, and looks for it in
.github/, the root, docs/ and then the owner's .github repository; this package
does the same walk through FileService and returns the platform handles and
custom URLs.

Parse is callable on supplied content, so a consumer that already has the file
does not need a FileService. The parser covers the flat subset GitHub accepts
(scalars, quoted values, inline and block lists, comments) and ignores keys it
does not know, so a file using a platform added later still parses.

Closes git-pkgs#174

@andrew andrew 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.

Thanks for picking this up. Discovery order and the mocked FileService tests match the issue. The parser is the main problem.

The hand-written parser rejects valid FUNDING.yml files, and Discover then returns an error for the whole repo:

  • An unknown key with a block list (new_platform:\n - a\n - b) fails with "list item outside a list key", because Parse clears pending for every key and then skips unknown ones. That contradicts the goal of still parsing files that use a platform added later.
  • A flow list split across lines (custom: ["https://a.example", then "https://b.example"]) fails in parseInlineList with "unterminated list".

GitHub reads the file as YAML, so please replace Parse's hand-written parser with go.yaml.in/yaml/v3, unmarshalling into a struct. github and custom accept either a single string or a list, so they need a small type with UnmarshalYAML that handles both. The module also builds under TinyGo, so the tinygo CI job has to stay green. Keep the table tests and add cases for the two shapes above. That also removes stripComment, parseInlineList, unquote, the flush closure and the long Parse doc comment.

Smaller things:

  • Links.URL never uses its receiver. Make it func URL(platform, handle string) string before it becomes public API, and add otechie to TestURL.
  • Location is exported, but nothing public takes or returns it. Rename it location.
  • The HTTPError 404 branch in isMissing can't be reached. Every backend already maps a 404 to ErrNotFound (github/files.go, gitlab/files.go, gitea/errors.go). Drop it, the net/http import, and the second half of TestDiscoverReturnsOtherErrors.
  • Cut the doc comments down to a line or two. The Discover comment is 12 lines, the Links comment about field names vs button labels can go, and the locations comment repeats what Discover says about stopping at the first file.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add reusable repository funding discovery

2 participants