No specification of "references" section
david-christiansen opened this issue · 9 comments
Summary
In the advisory template, there's a references section in the front matter:
[[references]]
type = "ARTICLE"
url = "https://example.com"
However, neither this section nor the extended example with all the comments describes what the valid entries for the type field are.
@david-christiansen the README has some explanation. Feel free to copy/paste it to other relevant places.
Or someone else will get to it soon :)
I'll add an explanation in the cli error
This comes from me role-playing a contributor, and they'll not be doing the command-line, right? The expected workflow is a pull request.
I'm a bit skeptical of copy-pasting information around, rather than having a single canonical source - is this perhaps evidence that the format docs are spread too much around and could be reorganized into a single file?
I mean, I am serious, I came across this pitfall doing mine, but I was too lazy to fix it (to read fully the documentation too).
I agree you can't ask the contributor to run the check locally, but accurate/contextualized error messages is a way to ease contribution and would be displayed in the CI run result.
I just got it in the CI, and I now understand what you meant. Good point!
I think that it would also be useful for the CI to not show all the ones that pass, or to at least split passing and failing files in the output. I imagine that when we have 100 entries, it'll be hard to find the error messages to act on.
(sorry if the smiley came across as sarcastic, I was trying to communicate "yay, someone's doing it" not "what a silly answer")
I may have been a bit defensive, sorry for that (I thought you didn't thought it was that of a big deal since you discovered during role-playing).
For sure, it would be good to have a bot that can give richer feedback in PRs to help contributors. For now, we should just improve the docs, because there are still quite a few tooling enhancements on the critical path (OSV export, website builder, etc).
I think that this improvement to the CI is great, as most people don't proactively read docs. This will help. Thanks @blackheaven!