Contribution Guidelines
This page defines the recommended contribution process for the UbID documentation and related technical references.
UbID documentation should remain accurate, secure, consistent, and useful for developers, integrators, institutional stakeholders, and technical reviewers.
Contribution principles
All contributions should follow these principles:
- Accuracy: document what the system actually does, not what is only planned.
- Security first: never expose secrets, tokens, private keys, credentials, passwords, or sensitive infrastructure details.
- Consistency: use the same terminology across all documents.
- Traceability: architectural changes should be connected to design decisions, implementation notes, or configuration references.
- Clarity: write for technical readers, but avoid unnecessary ambiguity.
- Production awareness: separate local development examples from production deployment instructions.
Terminology standards
Use the following terms consistently:
| Concept | Recommended term |
|---|---|
| Ecosystem | UbID |
| Credential issuer | Issuer |
| User wallet | Holder / Vault |
| Credential validator | Verifier |
| Secure recovery infrastructure | Recovery Cloud / Gateway |
| Verifiable credential format | SD-JWT VC |
| Issuance protocol | OpenID4VCI |
| Presentation / verification protocol | OpenID4VP |
| Local browser storage | IndexedDB |
| Browser cryptography | WebCrypto |
| Biometric / device authentication | WebAuthn / Passkeys |
| Face verification | FaceTec |
| Future secure messaging | DIDComm |
Avoid mixing old project names with UbID terminology unless the document explicitly explains upstream origins, compatibility, or inherited components.
Branching workflow
Create a dedicated branch for each documentation change:
git checkout -b docs/update-topic-name