Contribute to the protocol¶
Maintaining Legible also begins with what someone notices and can formulate, whether in a cumbersome test, an explanation that does not hold up or a condition the project overlooked.
Questions you can contribute to¶
Investigate something encountered in use: an explanation that is hard to understand, a condition missing from the specification, a cumbersome file exchange or a configuration need. You can formulate another question too. There is no need to wait for maintainers to create an assigned task.
You can present a critique, a report, a text correction or code without having to solve the whole problem. Read relevant materials and accessible proposals in the project's GitHub repositories. Present your observation, uncertainties and evidence you can share. A note or report can start the conversation; Appoints, Traces and Nods are not required to submit a correction.
Report an experience¶
When reporting an experience, explain what you tried to do, which tool or model you used and where the path helped or required effort. If you compared it with your usual practice, describe what changed, distinguishing what you observed from what you still suspect and sharing only necessary, authorized excerpts.
In collaboration, consider both people. Was preparation easier for the sender while reading took the recipient more time? Did someone need to explain again what the record should have contained? These accounts guide improvements to the writing, instructions and components.
Discuss and correct the materials¶
Identify the page, section and edition. Quote the passage and explain your objection or suggested change. Critiques of the book and paper can be discussed independently of the code. If a proposal changes a protocol rule, describe its effect on formats, interpretation and tests.
Develop code and configurations¶
Consult the existing components before starting. An integration can evolve without changing the specification. Include an example that reproduces the added or corrected behavior, with versions, dependencies and required access.
Preserve, present and incorporate¶
A proposal may be accompanied by a genealogy draft or pertinent Legible records. An Appoint can declare a formulation; a Trace, its dependency on other works; a Nod, a consequence already received. These records are optional: you can present a proposal without issuing any of them.
On GitHub, you can open an issue to begin the discussion. To suggest file changes, submit a pull request, which presents the changes for maintainer review. Both a draft and pertinent records may accompany that submission. Issues and pull requests are not, by themselves, Legible records.
Maintainers decide what to incorporate. That selection neither invalidates other formulations nor establishes a received consequence. To continue a path not incorporated, retain the files and references you may keep. Interested readers also need to consult proposals under discussion; downloading the main branch does not include files from unmerged PRs.
Links to the repositories and their Issues appear at the end of this page. Reports and proposals are submitted through GitHub.
Participate in maintenance¶
You can start with reviews, documentation or corrections and express interest in maintaining a component. Responsibilities and permissions are agreed as collaboration develops. Maintainers review what enters the repositories and site. Independent proposals also have a publication path.
Contribution license and publication¶
When submitting material for incorporation, confirm that you can provide it under the destination's license. Text uses CC BY 4.0; original code and formats use Apache-2.0. Preserve third-party notices. If text is only for discussion and is not being offered for incorporation, say so. Authors retain their rights under these licenses.
Stating that text is for discussion only makes clear that it is not being offered for incorporation into the project's files. If you publish it in a public GitHub issue, others can read it and the publication is subject to GitHub's Terms of Service. If those conditions are not suitable for the material, agree on another submission channel with the maintainers before sharing it.
Submitting to a public repository makes the content accessible there. Confirm the rights and authorizations needed to provide it under the applicable license. Contributions may persist in Git history and third-party copies; removing them from the current version does not automatically remove those copies. To request a correction or removal of content published by the project, send a message to the maintainers through the contact channel listed on the site. You do not need to create or sign a Legible record to make this request. Removal from the publication does not automatically revoke licenses already granted; see the publication notices for the conditions and limits of this process.
Submitting a correction requires no Appoint, Trace or Nod. Publication of records, names displayed on the site or contacts has its own review and selection. See the publication notices.
Offering code or text for incorporation¶
All three repositories adopt DCO 1.1 and require
cryptographically signed commits. After reading the certification and reviewing
your submission, use git commit -sS: -s adds the Signed-off-by sign-off,
and -S signs the commit. The sign-off's name and email become public; configure
an address suitable for that use before committing.
DCO concerns your right to offer the material under the relevant license; it does not transfer copyright to the project or replace a Legible record's NCO. Publishing a record or reference does not change the license of the cited work or evidence. Disclosure and personal data require their own examination, including when AI helped prepare the submission.
Questions, critiques and discussions require neither DCO nor Legible records. You can submit a pull request solely to discuss a proposal, but before incorporating the changes, maintainers must check the DCO sign-off, commit signatures and permissions to use the submitted material. See the full policies for protocol and website, as well as the policy for books and papers.
Channels¶
GitHub Issues is the channel for questions, use reports and proposals. Choose the repository according to the subject:
- Protocol, specification and reference code.
- Site pages and behavior.
- Book, papers, translations and references.
An issue lets you present a question and discuss it. To propose a change to the files, open a pull request in the same repository.
GitHub organization · Protocol repository — invitation required · Website repository — invitation required · Books and papers on GitHub — invitation required · Contact
Report vulnerabilities through the private security channel.