# (Proposal) Code distribution for our set of convention schema tools

**URL:** https://farmos.discourse.group/t/proposal-code-distribution-for-our-set-of-convention-schema-tools/1796
**Category:** Conventions
**Created:** [November 20, 2023, 3:37pm UTC](https://farmos.discourse.group/t/proposal-code-distribution-for-our-set-of-convention-schema-tools/1796 "2023-11-20T15:37:44Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![OctavioDuarte](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/octavioduarte/32/1443_2.png) [@OctavioDuarte](https://farmos.discourse.group/u/OctavioDuarte)
#### Post date: [November 20, 2023, 3:37pm UTC](https://farmos.discourse.group/t/proposal-code-distribution-for-our-set-of-convention-schema-tools/1796/1 "2023-11-20T15:37:44Z")

</div>

# JSON Schema Distribution Tools: Next steps.

The current situation is:

- We have a system that enables a user to write very complex JSON  
schemas leveraging the FarmOs format using high level functions with  
meaningful errors and methods.
- The system allows easy documentation, publication and sharing with  
minimum effort.
- The system allows to share standalone JS code validators, usable  
both in the browser and on a server, with 0 dependencies. These, as  
all JSON schenma, provide meaningful errors to suers wanting to  
validate.
- All the functionality is condensed in a GitLab monorepo.
- Consistency is validated via a non standard JSON schema property,  
but we still are able to offer both the schemata and our validators.

## Improving Code Separation

This library has been built with the intention of obtaining a maximum  
profit of the standardization work the user performs in a unique set of  
files contained in the folder `definitions`. There should always be a  
way to leverage all features by only populating the intended set of  
conventions. This is always coupled to abundant data examples to keep  
everything constantly tested and provide full feedback to the users of  
the extent any modification they perform might have. Of course, that  
design does not stop any user from modifying the **open source** code  
providing all the features in any way they want. As a minimum, having a  
full implementation can inform any new developers and serve as a working  
example.

We want to split this monorepo into up to several independent repos,  
which we believe brings a lot of advantages. There are up to three  
**deliverables** we might want to split from the current monolithic  
offer.

- The `convention~builder~` library, which provides the interface to  
build complex linked schemata involving many FarmOS entities.
- The `repo~structure~` which enables the easy and automated  
publication of schemata, documentation and code validator libraries.
- The `open~teamconvention~`, our first proposed set of conventions,  
which can be used by other organizations as a base and is also a  
concept validator for us while we develop the whole system.

### What's being pulled out into an NPM Package?

1. Stage 1: The `convention~builder~` library.

2. Stage 2: The `repo~structure~`.

3. Stage 3 (no extra work): Open Team Convention Set

### How many packages are created?

Up to three, as described in the previous section.

### Who can contribute to each package?

Being hosted in public git repositories, anybody can read the code,  
suggest changes, ask for help, etc. Better separating concerns across  
repositories probably makes it way easier, as less is happening in each  
repo, each one is more focused and adequate documentation can be exposed  
in the central spot for each one.

### When will updats happen?

With this new separation, updates will happen less often for each part,  
and the user will have the option to test how his conventions deal with  
the new code before updating, or even choosing if they want to update at  
all. The user's set of conventions, as well as the sources they've  
chose, will have the most frequent updates, as effectively they are  
required to change each time the conventions change in any way. The  
structure should eventually achieve all the first intended  
functionalities and depending on the userbase's intention could become  
quite static soon. The `convention~builder~` library will be updated  
only when new features need to be added or bugs need to be fixed.

### How is the process of creating a new Farm Convention changed? what's the new process?

We currently propose **forking our repo and incrementally applying  
changes**. This is easy and fast, but has proven to be counterintuitive.

The new process implies a fairly standard development procedure.

1. Start a new Git repo. (`git init`)
2. Start an NPM module in that repo. ( `npm init` ).
3. Install the two involved libraries, `npm install  
convention~builder~ convention~schemapublisher~` ).
4. Initialize the repo calling the convention~schemapublisher~ helper  
functions, as it is currently done to initialize projects in React,  
Vue or docusaurus. This will provide all the basic configuration,  
structure and files.
5. Set up the required CI variables (repo name, npm publication  
credentials, convention set name, etc). Of particular interest is  
the source of the basic FarmOS schemata, which can either be a farm  
or another repo.
6. (optional) If you want to inherit conventions from another repo,  
list them in a very simple JSON or YAML config file, which will have  
a format in which for each repo a user can either request all  
conventions, all conventions of several types (like "everything  
starting with 'log–activity' and everything starting with  
'asset') or cherrypick individual conventions.
7. Writing definitions as explained in our tutorial and commiting them  
into either `staging` or `main` will trigger the CI process,  
test that the examples are adequate, publish the validation code,  
publish the conventions and publish the wiki containing all  
documentation. The links will also be clearly exhibited for the  
user.

```auto
<!-- -->

```

1. Updates which need to happen.

### If that affects Juliet, what does she need to do?

Juliette or any other user wouldn't need to do much: all their work is  
exclusively in the "definitions" folder. They could follow the (rather  
fast and easy) process described in the preceding section to initialize  
an **empty/new** project, copy the definitions there and get all the  
advantages of the new system without rewriting a line of their  
preexisting work.