Odoo-Packager.md

@@ -9,6 +9,86 @@ For detailed documentation look at [Docker Image repo](https://gitlab.crnd.pro/c
 
 - [Odoo Apps Packager](https://gitlab.crnd.pro/crnd/docker/odoo-apps-packager)
 
+## How to enable for your project
+
+To create new assembly you have to:
+
+1. Create new repository (we call them assemblies)
+2. Add configuration file ([see](#configuration-format))
+3. Add SSH deploy key with write access enabled
+   1. Create pair of SSH keys via `ssh-keygen -t rsa -C root@my-assembly-name`
+   2. Add generate key to [Deply Keys](https://docs.gitlab.com/ee/ssh/#deploy-keys) of assembly
+   3. Specify public key in [CI Variables](https://gitlab.crnd.pro/help/ci/variables/README#variables) `CI_SSH_PUBLIC_KEY`
+   4. Specify private key in [CI Variables](https://gitlab.crnd.pro/help/ci/variables/README#variables) `CI_SSH_PRIVATE_KEY`
+4. Add create ssh private keys and public key to CI Variables
+5. Add CI jobs to run packager (see [example](#example-ci-config)).
+6. Disable ability to push on stable branches even for Maintainers. All changes have to be made through merge requests.
+
+`NOTE`: we recommend to use *Squash* option on merges of assembly to reduce number of commits.
+
+## Assembly workflow
+
+Usually we use following workflow to update assembly
+1. Create new branch from stable branch. For example: 11.0-update
+2. Check that *packager* job have started on this branch. If it is not started, we have to start it manually from web: *CI/CD -> Run Pipeline*
+3. When job is completed and repository have changes, then there new commit will be created on that branch (11.0-update)
+4. Create merge request
+5. Review changes
+6. Merge to stable branch
+7. Pull changes to Odoo intances that are running this assembly.
+
+## Example CI config
+
+```yaml
+variables:
+    SERIES_BRANCH: '11.0'
+    CI_JOB_TOKEN_GIT_HOST: 'gitlab.crnd.pro'
+
+    PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.hidden-pip-cache"
+
+# Disable global cache
+cache: {}
+
+.pip_cache: &pip_cache_definition
+    cache:
+        key: ${CI_JOB_NAME}
+        paths:
+            - "${PIP_CACHE_DIR}"
+
+stages:
+    - package
+    - test
+    - deploy
+
+.do_package_definition: &do_package_definition
+    image: registry.crnd.pro/crnd/docker/odoo-apps-packager:d
+    stage: package
+    before_script:
+        - odoo-packager --info-only
+        - odoo-packager --version
+    script:
+        - odoo-packager
+
+do_package_on_commit:
+    <<: *do_package_definition
+    except:
+        variables:
+            # Do not run package on commits created by packager itself
+            - $CI_COMMIT_MESSAGE =~ /\[odoo-packager\]/
+        refs:
+            - web
+    only:
+        - /^11.0-.*$/
+
+do_package_manual_trigger:
+    <<: *do_package_definition
+    except:
+        - "11.0"
+    only:
+        - web
+
+```
+
 ## Configuration format
 
 The configuration file for packager have to be placed into the root of repository