Lexicon Community

Contributing

Effective 2026-07-26 (as amended) First adopted 2025-03-10 History

This is the Technical Steering Committee's guide for anyone interested in proposing changes to the lexicons repository. The organization is volunteer run, and contributions come in many forms; recognizing this is critical to having a diverse and inclusive organization.

Ways to contribute

  • Lexicon schema file changes, including introducing new schemas and modifying existing ones.
  • Documentation and guidance on how Lexicon Community lexicons are used and referenced.
  • Reference material, including proof-of-concept code and writings, that provide context and examples for others on how to use Lexicon Community lexicons.
  • Policy, governance, and process contributions to improve how the Technical Steering Committee works with the community and accomplishes the project's mission.

There are other ways that people can contribute, and this is not an exclusive list.

Before you start

The repository. The lexicons live at tangled.org/lexicon.community/lexicons, the source of truth. The GitHub repository is a mirror. The main branch is production: merged lexicons are published and resolvable on the network, and merge access is moderated.

Meetings. The Technical Steering Committee meets monthly, defaulting to 1:00 PM ET on the first Thursday of each month. Each meeting is published as a community.lexicon.calendar.event record, and current meeting information is announced on the forum. Check there if the schedule changes.

Existing discussions. Proposals, working-group threads, and past decisions live in the Lexicon Community category on the Atmosphere Community Discourse instance. Search it before starting: the idea you have may already be in motion, and joining an existing effort beats duplicating it.

Lexicon Garden. Lexicon Garden is an independent lexicon browser and validator. Use it to explore and navigate lexicons in the wild — ours and everyone else's — and to create lexicons of your own to experiment with schema shapes before you propose anything.

How to get involved

  1. Start a conversation — lead with interop. Ideas begin on the forum. We're not here to create lexicons for their own sake; the goal is to bridge people actively building toward interoperability. Point to the existing lexicon, application, SDK, or tool you want to interoperate with, name the builders already working in the space, and describe what a shared schema would unlock.
  2. Form a working group. Working groups are self-formed (no approval needed to begin). Announce the group and its documented objective on the forum so others can find you, and gather the people who want to do the work.
  3. Propose changes. Major changes (new lexicon schema definitions, modifications to existing ones, or the removal of a schema) are proposed as pull requests against the lexicons repository. Ideally, most of the discussion and agreement has already happened on the forum by the time a pull request lands: the PR represents that consolidated work, not a place to hash it out. Iterate and experiment with real applications and code, using Lexicon Garden to try out schema shapes.
  4. Review and approval. Review happens in the open, and anyone can weigh in. Pull requests can only be approved by Technical Steering Committee members; this is where the burden of judging whether a proposal is sufficient rests, once the work has been done. Pull requests carry an agreed-upon "do not merge before" date to allow adequate time for discussion, and approval follows the participation and quorum rule.
  5. Ship and announce. Merged lexicons are published through the official discovery paths (a schema record in the @lexicons.lexicon.community repository, with DNS records pointing NSID resolution at it) and announced on the blog and from @lexicon.community.

Best practices and considerations

Lexicon schemas vary in complexity and there is no single design pattern to draw from. Instead, consider how you would answer the following questions when designing and proposing lexicon changes:

  • What does the proposal accomplish, and can it be accomplished with existing lexicons?
  • Are common conventions used? Compared to adjacent Lexicon Community lexicon schema definition files, are fields and types that accomplish similar things named or presented in a way that makes them easy to understand? Are fields and types vague in naming or purpose?
  • Do all fields and types have relevant and helpful documentation? Is there supplemental or localized documentation or writings supporting the proposal?
  • Does the proposal include example records to demonstrate how they are used? Are the examples based on real-world scenarios that readers can use directly?
  • Are there example applications or reference material in the form of code that demonstrate how records and methods are constructed and invoked?
  • A pull request doesn't need a working group. Changes and proposals vary in size, impact, and area; not every pull request needs hefty proof or discussion. Technical Steering Committee members may approve and merge changes at their discretion.

Real-world use is the acceptance bar: use cases, examples, and production-ready code, configuration, and content make a proposal strong.

Changelog

2026-07-26
Restructured as the TSC's guide to proposing changes, and amended following the restructuring:
  • Retitled "Contributing"; a "Before you start" orientation added (repository, meetings, existing discussions, Lexicon Garden).
  • Working groups are self-formed; the TSC's gate is pull request approval.
  • The separate "collaborator" role is removed.
  • The source of truth moved to Tangled (GitHub remains as a mirror); proposals and feedback moved to the Lexicon Community forum.
  • Publication goes through the dedicated @lexicons.lexicon.community repository; merge approval follows the governance model's quorum rule.
  • The real-world-use acceptance bar and proportionality are stated explicitly: not every pull request needs a working group or heavy process, and TSC members may approve and merge at their discretion.
  • The standalone "How lexicons are updated" section, including the hotfix rule, is removed; updates flow through the same process as additions.
This document's home moved from the governance repository to this site.
2025-03-10
Adopted as part of the updated governance: contribution types, the working-group playbook, release process, and proposal best practices.