I’d like to propose we establish some standard processes for documenting conventions used in farmOS, in the form of a new Git repository managed by the farmOS community.
For background on what we mean by “conventions”, see: Conventions | farmOS
To quote from an earlier discussion:
A lot of the discussions thusfar have been focused on how to implement conventions in different ways (eg: with quick forms, config entities, JSON schemas, RDF/JSON-LD, tooling for validation, etc). But as a first step, I think we can start by creating some standard specifications for established conventions, and some community processes for proposing/updating them.
I’m imagining high-level documents, that describe specific types of data/processes, and how to record them in farmOS, using RFC 2119 keywords (MUST/SHOULD/MAY/etc).
We can develop a process for proposing/discussing/refining/accepting new conventions over time using GitHub pull requests.
These documents/conventions can also be versioned, and have a process for updating them over time as necessary.
This can follow a similar approach as module development, where the community can experiment and document their own conventions outside of farmOS core, and then propose them for inclusion “upstream” as an “official” convention. This can embody and standardize the community-based consensus process we’ve been using informally thusfar.
These documents can then be used as references when writing actual code. Ideally the documents would also include code examples in PHP, Python, and Javascript (and ideally ideally with automated tests so we can be sure they don’t break).
To kickstart this process, I’ve started a farmOS-conventions repository with a proposed roadmap and template structure. This is just a brain-dump, but if others agree that it’s a good start then perhaps we can move it to the farmOS organization and start working collaboratively on it.
I’ve also started a “work in progress” branch with draft “soil test” and “water test” convention specifications as an example. These would be opened as pull requests for discussion/inclusion if we think the general approach makes sense.
- Example soil test convention: https://github.com/mstenta/farmOS-conventions/blob/wip/conventions/farmOS/soil-test/1.0/index.md
- Example water test convention: https://github.com/mstenta/farmOS-conventions/blob/wip/conventions/farmOS/water-test/1.0/index.md
I’d love to hear thoughts on this and see if it would make sense to move it to the official farmOS GitHub organization.
Once we have some conventions established, we could pull them into farmOS.org via Gatsby like we do with the other docs (cc @jgaehring).
Related discussions/context:
- Creating a standard 'interpretation' layer on top of core farmOS schema
- Conventions as config entities
- https://gitlab.com/OpenTEAM1/OpenTEAM-Technology/-/issues/70
- farmOS Conventions notes · Wiki · our-sci / partners / Research Farm Roadmap · GitLab
- How SurveyStack uses farmOS · Wiki · our-sci / partners / Research Farm Roadmap · GitLab