update devrules

Devrules.md

@@ -1,15 +1,70 @@
-# Developeur 
+# Developers 
 
 This page is about to save time to a dev to quickly onboard to add a features or debug any issues. This is also a good start if you want just dev a plugin for a tribe.
+Visual studio theme @id:ms-vscode.cpptools-themes
 
-## Key points
+## git management
+
+**Relations between git branches and environment**
+
+Those branches are corresponding to various environment:
+
+- **branch `main` is used for the production only** and needs a pull request to allow developers changes;
+- **branch `staging` is used for testing** and needs a pull request to allow developers changes;
+- **branch `develop` is the current last working version under development of the application .** Writing changes is allowed for developers on this branch.
+
+Initialize a developer branch, each developer must create and checkout a new branch named `devel/${USERNAME}` to work.
+
+**Git process for developers**
+
+  1. Select a feature to develop or a bug to fix. ideally work on different files and isolated from other work done in parallel by other developers. This will avoid or limit problems when merging branches.
+  2. Before any change on your local repository, please previously :
+  - run a `git pull`;
+  - merge your branch with the last commit of the `devel` branch :
+    ```shell
+    git checkout devel/${USERNAME}
+    git merge devel
+    ```
+  - fix conflicts on your local repository if necessary.
+  3. Program your changes.
+  4. **Don't forget to test!** Check if your changes are working locally.
+  5. Commit local changes on your named branch: `git commit -am "[comment]`
+  6. Push on your named branch: `git push -u origin devel/${USERNAME}`
+  7. Merge your modifications on the `devel` branch : `git checkout devel && git merge devel/${USERNAME}`
+   - Fix conflict if needed.
+  8. Push on the reference `devel` branch your changes: `git push -u origin devel`
+  9. Return to your local git branch to avoid errors directly on the `devel` reference branch
+
+**Git process for product owner** (aka P.O.)
+
+  1. The P.O. can merge `testing` branch with latest commit of the `develop` branch **only if application is working and functional**.
+  2. Add a git tag on commit according [SemVer](semver.org/) standards: `git tag v[SEMVER_VERSION] -m "[comment]" "&& git push --tags`
+   - *This tag is essential to correctly track application versions and to integrate it into a CI/CD process that is standardized and compliant!**
+  3. Test the application on the related environment.
+  4. Then the P.O. can merge `main` branch with latest commit of the `testing` branch **only if application is working and functional**.
+
+
+## Common rules
+
+### Security
+
+-  **Never store any password, API keys or any another sensible information in the Git repository!**
+-  **Think twice before adding a package in your project, get answer about licence, audited or not,**
+
+### Performance
+
+- **use require function by loading only what you need**
+- **be a bootleneck hunter, use async when it is possible but keep your code readable and simple**
+
+
+## apXtrib Key points
 
 * this is a npm/yarn classical organization (package.json give you 1st info)
 * **Entry point** ./apxtrib.js
 * apXtrib is organize around an express.js api and respect the restFULL concept on an object.
 * An **object** has:
     - a unique objectName
-    - a metadata definition that describe each character to qualify an object
+    - a schema definition that describe each character to qualify an object
     - a route named ./routes/objectName.js from the api /objectName/ parameters to request acting on items of this objectName
     - a model named ./models/ObjectName.js that act on items
     - a language info in infolg/ObjectName.js 
@@ -29,19 +84,17 @@ This page is about to save time to a dev to quickly onboard to add a features or
   }
   ```
 * A **response** is structured as 
-```
+  ```
   {
-    status: mandatory Integer,
+    status: mandatory Integer,(web status code)[https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml]
     info: optional string,
     data: optional object 
   }
-```
+  ```
- (web status code)[https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP]
-
 * **Multilanguage management** depending of header.xlang request
-    - info:"#model#key" starting by # mean a file is available in ./nationchains/static/info/model_lg.json to match {key:"information in language lg}
+    - info:"|model|key" starting by | mean a file is available in ./nationchains/static/info/model_lg.json to match {key:"information in language lg}
   
-### apXtrib Coding Convention 
+## apXtrib Coding Convention 
 
 Standard: Eslint 6 with a .eslintrc.js
 
@@ -57,7 +110,7 @@ lib used for:
 In general try to not install other lib in your dev. An apXtrib town mayor have to globaly valid to add a new lib into apxtrib so if you do then you can only use your town to provide your service and cannot use other town to deal wwith.
 
 
-### CORS and global
+## CORS and global
 
 global variable into node:
 *  ${__base} is the current dir where project are install in case you need absolute path.
@@ -69,30 +122,33 @@ global variable into node:
 
 
 
-### route template
+## route template
 
-A route analyse (data structur and user accesright) a http request to act a model action
+A route analyse (data structure and user accesrights) a http request to act a model action
 
-### model template
+## model template
 
 A model is a logical to apply onto an object. It is indepedant of the interface
-export model to  make it importable into route or any other app
+export model to make it importable into route or any other app
 
 
 
-### Object organization
+## Object organization
+
+Object properties are strongly inspire of  https://schema.org/docs/schemas.html <br>
+
+Fom https://json-schema.org/learn/<br>
+    https://json-schema.org/understanding-json-schema/index.html<br>
+    https://json-schema.org/draft/2020-12/release-notes.html<br>
 
-Object properties are strongly inspire of  https://schema.org/docs/schemas.html
-Fom https://json-schema.org/learn/
-    https://json-schema.org/understanding-json-schema/index.html
-    https://json-schema.org/draft/2020-12/release-notes.html
 Warning: stay in those specification much as it is possible, try to use existing object like person, organisation, ....
+
 As it is still on draft, a Odmdb.js (Objectdatamodeldatabase) is managing any CRUD on json object
-Any apxtrib key word is prefix by apx to inform that it does not exist in JSON schema protocole. This can be change in the futur if json schema will be stable enough.
+Any apxtrib key word is **prefix by apx** to inform that it does not exist in JSON schema protocole. This can be change in the futur if json schema will be stable enough.
 
 An **object is defined by a schema** store into ./nationchains/socialworld/schema/objectName.json or tribe/tribeId/plugins/pluginName/schema/objectName.json
 It lists key definition of an item's object.
-Items object are store into ./nationchains/socialworld/objects/objectName/objectNameid.json or tribe/tribeId/objects/objectName/objectNameid.json
+In basic configuration Items object are store into ./nationchains/socialworld/objects/objectName/objectNameid.json or tribe/tribeId/objects/objectName/objectNameid.json. 
 If an **item have a language** properties:lang that describe in with language is used by this item. If the object item cannot be translate this means that it is a different object.
 
 apXtrib **convention to manage language** to get a schema in a language:lg :
@@ -110,7 +166,7 @@ A models/objectName.js manage all items of an objectName:
        { valueuuid: { key:value of object} }
 
 
-#### Object key description
+### Object key description
 
 Main properties key:
 * **description** a short description that can be use in GUI
@@ -156,7 +212,6 @@ person shema
   },
 
 
-
 **searchindex** array of index to generate 
      keyword "all"  => generate objectname/searchinndex/objectname_UUID_UUID.json = {uuid:{full key:value}}    
 * **nouserupdate** user cannot modify this field from a request (only internal process can change this)           
@@ -176,11 +231,38 @@ person shema
 
 ### Object Nationschains 
 
+This model manage the socialworld based on nations and towns to run a blockchain where a node is a town and a nation is a blockchain rules that any town respect.
+Rules are manage in Contracts.
+
+.models/Setup.js is the interface of this model, to create a node/town for dev that is an unchain town or for production that is a chain town (real node) [process of setup] (https://gitea.ndda.fr/apxtrib/apxtrib/wiki/Setup)
+
+A pagan have an uuid + public key + private key and belong to only one tribe at a time optionaly an email + login + psw to recover his login/psw into his tribe. His private key is the only way to prove a user his the owner of an uuid account. No one else than the pagan knows his private key.
+
+At a time:
+* A pagan belong to only 1 tribe.
+* A tribe belong to only 1 town.
+* A town belong to only 1 nation. 
+
+The blockchain register only data about pagan (uuid/publickey) 
+Each town is fully decentralized manage by a pagan with mayor role.
+**A mayor knows** pagans informations from all tribes (uuid, publickey and optionaly: login/hash password and any information store).
+**A Druid rent** a space to the mayor of the town in exchange of anything (fiat currency, services, ...).
+**Druid knows** all about his user he can ask and store any data (cipher it or not) about pagans hosted in his tribe space.
+With a contract a druid can generate token currency that are valuate by stacking the equivalent of crypto's nation into the mayor wallet. Druid then can distribute as he wants those token to his community of pagan to value Pagans activities.
+
+A pagan can at any time convert a token in his equivalent in the crypto's nation. Then token's druid are destoyed. 
+A pagan owns data store into the blockchain and can request to move from tribe A to tribe B. By doing this all token owns will be convert to crypto's nation and all specific data will stay the properties of Druid or not(can be removed by him or not but Pagan will have no more access to it).
+
+
+
 
 ### Object Contracts
-
+A contract is a script js that is apply into the blockchain to register important transaction into the social world.
 
 ### Object Tribes
 
+Tribes are localy manage, by a pagan that have mayor role that can Create Delete a ./tribes/tribeId 
 
 ### Object Pagans
+
+Pagans is managed by a pagan that have druid role for his tribe. He can host any other pagan. A pagan can only belong to one tribe