Gitlab hosts a list of „Epics“ in the Kicad Sources. As far as I can see, this is a loose collection of issues each one showing diffrent states but similar topics. Some of the Epics itself have „closed“ state, while others contain a mixed collection of closed and none closed issues states.
What is the purpose of Epics and what happens with them ? They are not intended to submit any patch or further spec-doc ?
Some of the issues show status „awaiting-spec-doc“. Assume this state label is assigned by lead devs who did not understand the issue because of foggy description ? Where is the home of „spec-docs“, what format do they have and who is allowed to submit them?
Some of the issues were active for a long time but not solved by merge request nor have the awaiting-spec-doc issued. Is it possible to re-open them to add a spec-doc or patch ?
Epics are just ways for us to group issues together, there’s no real rhyme or reason for how we use them other than to keep track of things. Sometimes it’s because we have a larger goal, other times its just so we can find issues later in historical review in a more easy manner. Some Epics may be open indefinitely, some are temporary, etc.
If you want to work on an issue, feel free to reply to one to express interest and we’ll see it. Or just open a MR against an issue if it’s a straight forward fix. We do not accept patches in issues, we want MRs.
awaiting-spec-doc has been mainly used as a placeholder by the core devs. We create an issue outlining a future goal item and mark it “await spec doc” because it hasn’t been planned out fully. It also means that item is significant amount of work and will be visited at some point in the future but it’s otherwise equivalent to a “wishlist” item in priority.
It’s an agile concept as part of a storyboard.
Many issues/feature-requests might come under one epic as means to groups related issues.
It’s useful as different people might be interested in working on one area (eg pcbnew or a specific feature) and thus grouping them brings focus in one area and thus someone may fix/implement the issue.
Ok, spec docs may explain a single problem area or concept suggestion of Kicad as a prerequisite to implement one or more issues. This seems similar as an extension to Epics but they are not part of them. There seems no home of spec-docs and there seems no procedure like a MR to issue them to to the kicad-dev-docs project or anywhere else.
Spec docs are built ad-hoc when needed and historically live on Google Docs. There is not a public RFC process; the spec docs are just made when needed to help the developers working on a particular feature decide on a plan.
Is there any way to link spec-docs from issue or Epics ? E.g. your doc contains valuable information and is not a part from any MR and neither goes to source code nor the dev-docs.
We can insert links, however this document was mainly meant to organize my own thoughts and communicate them with other devs during the initial implementation discussions, not to live on forever as a public thing. Not that it is private, but it also is not maintained and now that the code is merged it doesn’t really have a purpose.