4:01 p.m.
(Not sure how I missed sending these out; sorry about that!)
Attendees:
Ivan, Matthew, Heather
Notes:
0 - Agenda bash
1 - Administrivia
Note that GÉANT has a tender open for idpy developers. No public link, but if anyone knows
anyone that might be interested, a job description has been posted to the #random channel
on idpy slack.
2 - Documentation
FAQ vs in-line documentation in the code. The FAQ idea of using responses in issues was
very disorganized; Heather spent some time on that and found them not very useful. The
in-line doc as they stand today aren't sufficient. The functions aren't documented
sufficiently to actually tell someone how to use them. But if we do add the how-to to the
doc string, they'll be too long. Ivan sees the separation being "what it is"
is in the doc string, but "how to use it" should be in a different place.
Even with the idea that the doc strings being just descriptive, they are falling behind
and are not complete.
Matthew points out that he's having to read a lot of source code to figure out how to
implement the code. This works well enough for him, but it's hard to teach reverse
engineering to new developers. There is good example code out there, but there are places
where he doesn't even know he needs to go look at the sample code. What would like to
see online is everything: how to use it and the reference material (deep dive on function
calls).
We have a short configuration how-to (how to build a small SP or IdP) but it's very
basic on readthedocs.io. We could create a list of what we want to display there (e.g.,
how to create a custom SAML response, how to validate a signature, how to create a SAML
request, how to get custom metadata). Part of the answers to those are in the Issues and
PRs, and some are in the code itself. We'll need to improve the code (doc strings) at
the same time. Let's start with a small list (see examples above).
Ivan is also working on a few small
documents: release.md, security.md, developers.md, contributing.md. These answer things
like how to create a release, how the code should look, what tools we use, what the doc
strings should look like, how to write tests, how to report an incident, where the
security policy is located.
See https://docs.github.com/en/repositories/releasing-projects-on-github/automa…
For additional documentation, create a new file
here: https://github.com/IdentityPython/pysaml2/tree/master/docs
This will create a new page on readthedocs.io and we can crowdsource answering the
questions. Need to use the .rst format. Start by just adding the files to the top level;
we can reorganize into folders later.
3 - GitHub review
a. OIDC - https://github.com/IdentityPython (JWTConnect-Python-OidcRP,
JWTConnect-Python-CryptoJWT, etc)
b. Satosa - https://github.com/IdentityPython/SATOSA
How should we announce the new docker container? The old repo is still around; should it
be removed?
Matthew will draft text for the announcement; aim to post on the website and post in an
email. Ivan will point to the official images in the repo.
c. pySAML2 - https://github.com/IdentityPython/pysaml2
d. Any other project (pyFF, djangosaml2, etc)
4 - AOB
Thanks! Heather