Improve documentation about algorithm implementation sources

dstebila commented 2 months ago

We should improve our documentation on the sources of our algorithm implementations, including:

what the source is for the upstream implementation (and, if necessary, what upstreams are above that)
where the preferred destination is for bug fixes to that implementation (upstream? via patches in liboqs copy_from_upstream)

The address of the immediate upstream is included in algorithm datasheets in the docs folder, but not the deeper information described above.

It is also not immediately obvious to people new to OQS where this information can be found.

dstebila commented 2 months ago

Note that @jplomas suggested using Github actions for monitoring activity on upstreams.

jplomas commented 2 months ago

Elaborating on meeting discussion points, I am happy to develop automation tooling to flag upstream commits/issues for review. It would be helpful to have some thoughts and input into where the flagging is done, as I have a reasonable idea of the mechanism and steps to achieve this.

Options are:

1. As tagged issues on liboqs (with a label, e.g. `upstream: foo` or `upstream: bar`)

Pro:

Natural location, the obvious place to look for newcomers to the project

Con:

Likelihood of polluting liboqs issues with lots of upstream activity of little to no impact, distracting from more focussed tangible issues

2. Tagged issues on an `upstreams` repo

Issues with tags as above, but on a separate repo, which consists of a simple config file of the repos we are monitoring

Pro:

Separation of issues from those arising directly from liboqs code
Open and transparent

Con:

A large backlog of issues could be seen as a negative quality indicator

3. Static site: generated list

For review/discussion (and allocation of reviewers/manual creation of issues as necessary) on status calls

Pro:

Manual review/triage review before a GitHub issue is created
Degree of separation from liboqs repo

Con:

Degree of separation from liboqs repo

To me, it is s straight choice between 2 and 3.

baentsch commented 2 months ago

I don't quite see the Con on option 3 if there'd be an option to auto-upload this file to a Wiki page (?) That way it can be manually curated by anyone willing to do so...

jplomas commented 2 months ago

I guess this is an unfamiliar / different process to handling issues and workstreams than some contributors would be used to. Essentially taking the workflow one step beyond the GitHub platform - and all the benefits that affords.

Not necessarily entirely negative.

(FWIW I think 3 is still my preferred option)

baentsch commented 2 months ago

(FWIW I think 3 is still my preferred option)

So it is mine. Thanks again for the offer to take this on to improve OQS' stability -- and now these proposals! Please let us know whether there's more feedback you'd like to get.

dstebila commented 2 months ago

I do feel overwhelmed by the number of issues in liboqs already, and I agree 1 could make it worse. If the repo in 2 is used solely for this purpose, then I'm not so worried about it as a quality indicator, but we still might struggle since we haven't yet mastered Github issue management/organization. So maybe 3 gives us the most flexibility -- in some sense, that's a similar approach to the small CI dashboard at https://openquantumsafe.org/dashboard.html.

jplomas commented 2 months ago

Thank you, that's ample consensus for me to try and put something together. The rest of my month is pretty busy but will see what I can do.

open-quantum-safe / liboqs