2024-08-18 - Progress on closing GitLab issues

At the time I started writing this post (about three months ago), there were 42 open issues at the two gitlab.com repositories which were set up by Sean Conner to assist efforts to finalise the Gemini specification in 2021. Of these, 25 were related to the network transport protocol, and 16 were related to the "gemtext" markup format:

GitLab repository for the transport protocol

GitLab repository for the gemtext format

Today there are 31, because since starting I have closed 11 of them, about one quarter of what was there. Of those 31 remaining issues, 19 are related to the network transport protocol and 12 are related to the gemtext format, roughly a 60:40 split. My hope is that by the end of this year, that GitLab repositories can be decommissioned and either removed or replaced with simple notices directing people to geminiprotocol.net. That means closing as many issues as possible and making sure those which aren't yet closed are clearly documented elsewhere so that nothing is lost.

The rest of this post discusses which issues I have already closed, summarises the remaining open issues, and offers a rough roadmap for moving toward zero issues. Throughout, issue numbers assigned by the GitLab trackers are prefixed with P for the network transport protocol repository and G for the gemtext repository.

Closed issues

All the issues I have closed were ones which had already been solved. In many cases the original work to close these issues was done by Sean Conner in his updated specification, also hosted at GitLab, and then carried over into the official specifications I published this year at geminiprotocol.net.

• P04 asked for an explicit limit on redirects, which is now in place.
• P09 correctly pointed out that response code 44's old specification conflicts with the generic 4x specification. This flaw was pointed out by immibis, thanks! I updated the specification in late February of this year solving the problem.
• P19 asked for clarity on what should happen when a request with a user input component results in a response of type 10 or 11. The new spec is explicit on this. This issue was opened by John Cowan. Sean, nevuri, Luke Emmet, makeworld, Philip Linde and others contributed to a pretty thoroughly discussion of options. Thank you all!
• P20 requested the removal of some incorrect language around the use of text/gemini's lang parameter to determine whether text should be rendered left-to-right or right-to-left. This was opened by Stéphane Bortzmeyer and fixed by Sean, thank you both.
• P22 requested that a copyright license be specified for the specifications. This issue was also opened by Stéphane, I strongly suspect in response to discussion on this matter on the mailing list initiated by DJ Chase. Sean Conner CC0 licensed the new network protocol spec. Thanks everyone! I originally retained CC0 only for the protocol spec and chose CC BY-NC-ND for the gemtext spec. With the 0.24.0 release I actually switched the gemtext spec to CC0 as well, based on conversations I had with some parties.
• P27 suggested replacing the use of "not awful" in the discussion of TOFU with more formal language. This request was made by Mansfield and implemented by Sean. Thank you, both! The old language is gone from the formal specification but still exists at the moment in the technical overview, but I am declining to change it for now. I agree that this kind of language is out of place in a formal specification document, but it's fine in an informal overview.
• G05. Asked for clarity on allowed line endings. This issue was opened by Felix Queißner. The current official specifications make this pretty unambiguous. The specification of gemtext uses CRLF exclusively because this is how subtypes of the MIME media type `text` must be defined. The specification of the transport protocol relaxes this requirement by allowing consistent use of either CRLF or LF and mandates that clients accept either.
• G07 presented an ABNF specification for gemtext, written by Sean. Somehow I wrote my own from scratch before realising this one existed! I feel bad about this duplication of effort. But we have an ABNF spec now, so the issue can be closed.
• G09 requested another change of language with regard to left vs right rendering of text, another Stéphane and Sean combo effort, thanks!
• G13 pointed out a typo where "Cyrillic" was misspelled as "Cyrllic". This was pointed out by John Cowan. A "Ghost User" (account now deleted) made a PR to fix this in the repo, but it was never merged. Thank you, both! The official Gemtext specification at geminiprotocol.net does not have this typo, I guess it was fixed somewhere along the line by someone. Thanks to that person, too! I have also made the corresponding change in the technical overview document which the old monolithic specification became (it will probably be removed in the future anyway as that overview is trimmed down, but better to fix it there too now). So, this is thoroughly dealt with.
• G14 requested clarity on what precisely constitutes a line in gemtext. I think that the presence of an ABNF formulation of a gemtext document which explicitly includes a symbol named "gemtext-line" now makes this entirely unambiguous.

Open issues

The 31 remaining open issues can be sorted fairly well into the following seven categories, listed in order of most to least issues:

TLS improvements (8 issues, ~26% of remaining)

• P05. TLS server trust
• P10. TLS and trust
• P12. Only allow client certs over TLS 1.3+
• P13. Forbid OCSP requests
• P18. Limit certs to hostnames only
• P23. TLS session resumption
• P38. User fingerprinting through client certificate params
• P39. User fingerprinting through TLS Client Hello

Gemtext specification defects (7 issues, ~23% of remaining)

• G16. Limits on Data URIs
• G15. Acceptable space
• G12. Clarify when a screenreader should read preformatted
• G10. Mandatory space after =>
• G06. Define edge cases around empty lines
• G03. Semantics of fragments
• G01. Clarification of lang param

Transport specification defects (6 issues, ~19% of remaining)

• P03. Clarify META
• P08. Frags and redirection
• P15. Display of errors to users
• P17. Remove status type 11
• P33. SNI and IP addresses
• P36. Unicode BOM chars

Internationalisation questions (3 issues, ~10% of remaining)

• P01. URI vs IRI.
• G08. IRIs on link lines
• G04. URL vs URI for link lines

Organisational issues (3 issues, ~10% of remaining)

• P16. Formal registration of the port
• P06. Registration of URI scheme gemini://
• G11. Register media type

Feature requests (2 issues, ~6% of remaining)

• P45. Better input support
• G17. Escaping ```

Application recommendations (1 issue, ~3% of remaining)

• P37. CSRF protection

A rough roadmap

I consider the two "specification defect" categories the highest priorities. Together they constitute 13 issues or about 42% of what's left. A couple of them I am confident making small unilateral decisions on and I'll try to close those soon. Some of them I actually already very nearly closed, but have kept them open just to remind me to tidy up a few loose ends. Others, I don't necessarily think are difficult, but as mentioned previously, I want to be more cautious in general about making potentially breaking spec changes and I want to consult with some trusted advisers before steaming ahead. I would still love and genuinely hope to get all 13 of these issues closed by the end of this year. The issues dealing with fragments are probably the most non-trivial decisions still to be made.

The next largest category after these two are the TLS related issues. Many of these, I think, are not actually within the scope of either of the formal Gemini specification documents, but rather belong in either the Best Practices document or possibly a new TLS-specific guide to best practice. I do in fact already have plans for such a document and although I haven't touched in on the subject for a while I even have other people who have already expressed willingness to help. A similar thing is true of the CSRF protection issue, in fact, and a specific new document which addresses that issue will be published at geminiprotocol.net very soon!

The URI internationalisation issues certainly are within the scope of the specification documents. I am still sticking to my previously announced plan to get everything else sorted out first before giving this question too much consideration.

There has been some small progress, or rather, attempted progress, on the "organisational issues" category, made earlier this year. I will make a news post about this before the end of this year explaining the situation.

Surprise, surprise, I sure don't like the chances of those feature requests...