feat: update release doc

0871935e · Bastien DUMONT · d14bd9b7 · 0871935e · 0871935e · 0871935e
Commit 0871935e authored 2 years ago by Bastien DUMONT
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -16,6 +16,7 @@
    "ecogestures",
    "ecolyo",
    "Ecolyo",
+    "ecolyodemo",
    "ecolyotest",
    "enedis",
    "Enedis",

--- a/docs/ecolyo/index.md
+++ b/docs/ecolyo/index.md
@@ -9,7 +9,7 @@ This is a [Cozy](https://docs.cozy.io/en/) application that allows users to conn
 !!! danger "Reminder"
    If you're a new developer tasked to work on this project, please get acquainted with the team [processes](https://forge.grandlyon.com/web-et-numerique/factory/wiki_web_num) and read the advised [dev environment](https://forge.grandlyon.com/web-et-numerique/factory/wiki_web_num) documentation and the self-data [prerequisites](../index.md#installing-prerequisites).
-## [Ecolyo.com](ecolyo.com)
+## [Ecolyo.com](http://ecolyo.com)
 Ecolyo has a public landing page that showcases features.

--- a/docs/ecolyo/technical/deploy.md
+++ b/docs/ecolyo/technical/deploy.md
-# Deploy Ecolyo
+# Deploy Ecolyo for development
 This section will show you how to deploy your project on different environments.
-## Deploy build to builds branches
+## Builds branches
 3 builds branch are today available for Ecolyo:
 - **build**: reflect the build of the master branch and the version deployed in production environment
- **build-dev**: reflect the build of the dev branch and the version deployed on dev environment
 - **build-test**: reflect a temporary build which can be used for test purpose
+- **build-dev**: reflect the build of the dev branch and the version deployed on dev environment
-!!! info "Windows users"
+## Deploy to build branches
-    Some command did not run on Windows. Please use your Linux distribution installed on your WSL. For more information about it see the [Install WSL section](../../wsl.md)
-Make sure that:  
+Make sure that:
 - you are on the right branch (dev or master) depending on the environment you need to deploy.
 - your branch is up to date
@@ -38,40 +37,20 @@ yarn deploy
 ## Auto deploy for dev
-In order to prevent manual action for deployment, a gitlab-runner has been configured to deploy every changes on the `dev` branch on our test [env](https://ecolyo.ecolyodemo.cozy.self-data.alpha.grandlyon.com/)
+In order to prevent manual action for deployment, a gitlab-runner has been configured to deploy every changes on the `dev` branch on our [ecolyodemo](https://ecolyo.ecolyodemo.cozy.self-data.alpha.grandlyon.com/) env
 !!! info "cicd scripts"
    You can find all scripts used in cicd jobs on the following [repository](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo-infra-scripts)
-## Deploy build-test branch to one Scaleway instance for testing
+## Deploy build-test branch to a Scaleway instance for testing
 You can directly use the content of build-test branch to update one instance for test purpose.
 Simply use the dedicated script `update_ecolyo_test.sh <instance_name>` with the targeted instance (from the server).
-By default we use the ecolyotest instance for testing intermediate functionality.
+By default we use the ecolyodemo instance for testing intermediate functionality.
-For more information you can check for [Easy Cozy scripts](../../../easycozy/commands/).
 ## Deploy build-dev branch to all Scaleway instances
 You can directly use the content of build-dev branch to update apps on dev environment using scripts (from the server).
-Simply use the dedicated script `update_all_ecolyo_dev.sh` (from the server).
+Simply use the dedicated script `update_all_ecolyo_dev.sh`.
-For more information you can check for [Easy Cozy scripts](../../../easycozy/commands/).
-## Deploy build branch to Cozy
-You can deploy content of build branch into Cozy registry by using the cozy-app-publish command after replacing following value:
- $COZY_TOKEN : token provided by Cozy team
+For more information you can check for [Easy Cozy scripts](../../../easycozy/commands/).
- $VERSION_NUMBER: version of the application
- $COZY_SPACE: space of the Cozy
-:warning: Make sure that the **build branch** is up to date and was build with **prod configuration**
-```sh
-yarn cozy-app-publish \
--token $COZY_TOKEN \
--build-url https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/archive/build/ecolyo-build.tar.gz \
--manual-version $VERSION_NUMBER \
--space $COZY_SPACE
-```
-More information at [cozy-app-publish](https://docs.cozy.io/en/cozy-app-publish/#manual-usage-not-recommended)
--- a/docs/ecolyo/technical/gitflow.md
+++ b/docs/ecolyo/technical/gitflow.md
 # Gitflow
-## Initialize
+## Protecting branches
- Create a new project in gitlab and take note of its url
+Protected branches prevent anyone to push on the selected branch, the only way to add code to the branch will be using merge requests.
-### Protecting Master Branch
-On the gitlab page of your project go to _Settings/Repository_ in the _Protected Branches_ section.
-Select the **Master** branch and set **allow to merge** to **_Master_** and **allow to push** to **No one**
-This will prevent anyone to push on the master branch, the only way to add code to the branch will be using merge requests.
 ### Setting Development Branch
@@ -18,38 +12,11 @@ This will prevent anyone to push on the master branch, the only way to add code
 git clone https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo
 ```
- Create the development branch
-```sh
-git checkout -b dev
-```
- Init your project and then type any time you want to commit changes:
-```sh
-git add .
-git commit -m "Commit changes"
-git push origin dev
-```
 ## Start Developing
-For any other development you should create a branch from the development branch.
+### Branch naming
-First make sure to be on the **_dev_** branch, type:
+:warning: to be updated with the changes of Factory
-```sh
-git branch
-```
-> to see your current branch
-### Conventional Commits
-The commit contains the following structural **types**:
- fix
- feat
 In our team organisation we are using Icescrum to keep track of our User Stories (US). Each US is identified by a number. In order to easily identify the commit that refers to the US, a `feature` branch name should follow this structure:
@@ -71,17 +38,30 @@ You can create the branch by typing:
 git checkout -b fix/-<title_of_the_fix>
 ```
-**Breaking Change**
-Appends a `!` before the title of the commit to notify that a breaking change has happened. Give a solid description of the changes as well.
-**Types** other than fix and feature are allowed, for example _build_, _chore_, _ci_, _docs_, _style_, _refactor_, _perf_, _test_ and others.
+### Conventional commit
-**add tag**
+The [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary) is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
+The commit message should be structured as follows:
-```sh
-git tag -a 1.0.0 -m "complementary message"
 ```
+<type>[optional scope]: <description>
+[optional body]
+[optional footer(s)]
+```
+The commit contains the following structural elements, to communicate intent to the consumers of your library:
+* **fix**: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
+* **feat**: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
+* **BREAKING CHANGE**: a commit that has a footer BREAKING CHANGE:, or appends a `!` after the type/scope, introduces a breaking change (correlating with MAJOR in Semantic Versioning). Give a solid description of the changes as well.
+* types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
+* footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.
-### Gitflow Scheme
+## Gitflow Scheme
 ![Gitflow](/img/gitflow.png)
--- a/docs/ecolyo/technical/release.md
+++ b/docs/ecolyo/technical/release.md
-# Release Ecolyo
+# Release Ecolyo to Cozy
-## Conventional commit
+!!! abstract "Procedure summary"
+    - tag
+    - build
+    - deploy
+    - publish
-The [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary) is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
+## Pre-requisites
-The commit message should be structured as follows:
+Make sure that:  
-```
+- you are on the right branch (dev or master)
-<type>[optional scope]: <description>
+- your branch is up to date
+- you node modules are up to date
-[optional body]
+## Bump versions, Tag and create changelog
-[optional footer(s)]
+### manifest.webapp
-```
-The commit contains the following structural elements, to communicate intent to the consumers of your library:
+Checkout on the branch `dev` and bump the version number in `manifest.webapp`. Use a similar commit : _"bump manifest to X.Y.Z"_
-* **fix**: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
+!!! warning
-* **feat**: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
-* **BREAKING CHANGE**: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
-* types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
-* footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.
-## Release Ecolyo with Standard-version
+    Commit but don't push so pipelines are not yet triggered.
-[Standard-version](https://github.com/conventional-changelog/standard-version) is library javascript that allow to handle easily tags and changelog file.
+    You don't have to change the version inside `package.json`, standard-version will do it.
-To create a new release, you have to :
+### Tag with Standard-version
-1. the following command in order to create a release tag, bump package.json version and update changelog file.
+!!! question "Standard version"
-2. checkout on the branch `dev` and bump the version number in `manifest.webapp`. Use the following commit format: 'bump manifest version to X.X.X'
+    [Standard-version](https://github.com/conventional-changelog/standard-version) is library that facilitates creating tags and update changelog (it uses conventional commit so make sure you follow the guidelines described [here](./gitflow.md#conventional-commit)).
-3. then run the script
+A release script is inside package.json, run it or use the standard-release command :
-```bash
+```sh
-yarn run release --release-as X.X.X # replace with version number (ex: 1.2.0)
+yarn release 2.X.Y
+# Equivalent to
+yarn standard-version 2.X.Y
 ```
-4. once the command has finished, push with
+:warning: Do not push with VS Code
+The script will give you a command to push tags on the remote. (something like this, depending on the branch)
 ```sh
 git push --follow-tags origin dev
 ```
-:warning: Do not push with VS Code
+??? bug "Handle mistake tags"
-5. Finally, add release notes in gitlab in your [project -> repository -> tags](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/tags) -> **edit release notes**
+    If you see a bug in the Changelog (the last version doesn't compare without the previous version correctly or you have plenty of undesired commits from previous versions), it means you made something wrong when you pushed your commit (basically you may have made a classical git push instead of git push --follow-tags origin dev), and you tag is not correctly annotated or annotated with the wrong commit.
-You can copy paste the last changes in [CHANGELOG.MD](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/blob/dev/CHANGELOG.md)
+    You can list the annotated tag with the following command
-### Annotated Tags
+    ```sh
+    git tag -n
+    ```
-If you see a bug in the Changelog (the last version doesn't compare without the previous version correctly or you have plenty of undesired commits from previous versions), it means you made something wrong when you pushed your commit (basically you may have made a classical git push instead of git push --follow-tags origin dev), and you tag is not correctly annotated or annotated with the wrong commit.
+    A normal tag should have its related commit like this :
-You can list the annotated tag with the following command
+    ```
+    v2.1.3          chore(release): 2.1.3
+    v2.2.0          chore(release): 2.2.0
+    ```
-```sh
+    If you see some mistakes in tag annotation you can change it with the following command :
-git tag -n
-```
-A normal tag should have its related commit like this :
+    ```sh
+    git tag -a v2.1.3 COMMIT_SHA -m 'chore(release): 2.1.3' -f
+    ```
-```
+    This command will annotate an existing tag (v2.1.3 with chore(release): 2.1.3 here) to the right commit. You'll have to pass the commit_sha from the related chore commit.
-v2.1.3          chore(release): 2.1.3
-v2.2.0          chore(release): 2.2.0
+## Create a release
-```
+[Changelog.md](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/blob/dev/CHANGELOG.md) will be updated with commits of the current version.
-If you see some mistakes in tag annotation you can change it with the following command :
+To create a release, copy the content of the latest version bump and go to [Repository > Tags](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/tags) and click the edit button. Paste the version changelog inside the _Release notes_ and click create.
+## Deploy build
+After pushing your tag, the pipelines should be triggered.
+Verify that the **build** branch is up to date [Repository > Branches](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/branches)
+!!! note "Manually push build"
+    ```sh
+    yarn build:browser
+    yarn deploy #prod config
+    ```
+## Publish build branch to Cozy
+You can deploy content of build branch into Cozy registry by using the cozy-app-publish command after replacing following value:
+- **$COZY_TOKEN**: token provided by Cozy team
+- **$VERSION_NUMBER**: version of the application
+- **$COZY_SPACE**: space of the Cozy
+:warning: Make sure that the **build branch** is up to date and was build with **prod configuration**
 ```sh
-git tag -a v2.1.3 COMMIT_SHA -m 'chore(release): 2.1.3' -f
+yarn cozy-app-publish \
+--token $COZY_TOKEN \
+--build-url https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/archive/build/ecolyo-build.tar.gz \
+--manual-version $VERSION_NUMBER \
+--space $COZY_SPACE
 ```
-This command will annotate an existing tag (v2.1.3 with chore(release): 2.1.3 here) to the right commit. You'll have to pass the commit_sha from the related chore commit. 
+More information at [cozy-app-publish](https://docs.cozy.io/en/cozy-app-publish/#manual-usage-not-recommended)
+## Update master
+Once you're finish, you should create a [new merge request](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/ecolyo/-/merge_requests/new#) from dev to master.
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -28,6 +28,7 @@ markdown_extensions:
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
+  - pymdownx.details
  - admonition
  - plantuml_markdown:
      server: http://www.plantuml.com/plantuml
@@ -64,14 +65,14 @@ nav:
      - Technical:
          - Getting started: ecolyo/technical/launch_local_application.md
          - Architecture: ecolyo/technical/architecture.md
-          - Deploy: ecolyo/technical/deploy.md
+          - Deploy on alpha: ecolyo/technical/deploy.md
          - Doctypes: ecolyo/technical/doctypes.md
          - Environments: ecolyo/technical/environments.md
          - Gitflow: ecolyo/technical/gitflow.md
          - Libraries: ecolyo/technical/libraries.md
          - Mail: ecolyo/technical/mail.md
          - Redux: ecolyo/technical/redux.md
-          - Release: ecolyo/technical/release.md
+          - Release to cozy: ecolyo/technical/release.md
          - Remote Doctypes: ecolyo/technical/remote_doctypes.md
          - Scaffolding: ecolyo/technical/scaffolding.md
          - Services: