# Workflows

> [TOC]

## Issues Format

Every Github issue needs to be tagged with a `type`, `section`, `detail` (if applicable), `project` (if applicable), and `priority`

**type**
| Tag | Description |
| -------- | -------- |
| bug | unintended behaviour |
| feature | new behaviour |
| refactor | code refactor |
| chore | something that needs to be done under the hood but is not fixing an issue or a new feature necessarily |
| idea | feature still in early stages, a feature request |

**section**
| Tag | Description |
| -------- | -------- |
| chat | related to the chat section or chat functionality |
| wallet | related to the wallet section or wallet functionality |
| general | related to the app in general or functionality that affects all sections |
| onboarding | related to the login or new account functionality |
| profile | related to the settings section or settings functionality |
| node | related to the node management section or node management functionality |
| timeline | related to the timeline section or timeline functionality |
| browser | related to the browser section or browser functionality |
| internal | related to the app build or distribution or internal functionality |

if an issue affects multiple sections it should be tagged with section, if it affects the app in general then there is no section tag.

**detail**
| Tag | Description |
| -------- | -------- |
| crash | an issue that is causing a crash |
| ui | an issue that is purely an UI only issue |

**project**
| Tag | Description |
| -------- | -------- |
| wallet-redesign | an issue related to the new wallet redesign |
| communities | an issue related to the communities functionality |

**bugs priority**
| Tag | Description |
| -------- | -------- |
| `priority 0: blocker` | an issues that requires immediate attention and that causes the app to not work at all (e.g a crash) or an issue that can lead to loss of funds |
| `priority 1: high` | an issue that is extremely important to fix, that interferes with the majority of users, occurs often and prevents a user from using a feature and there is no workaround |
| `priority 2: medium` | an issue that is not severely affecting the overall app, it may interfere with some users users experience but there is a obvious workaround or the user might not even be aware this is a bug. should be addressed sooner than later, but it can wait if there more serious issues |
| `priority 3: low` | issue that is barely adversely impacting the product key features, might be apparent but it's hard to notice and is unlikely to affect most users, can wait if there are more serious issues, an issue with a high effort/low reward value |
| `priority 4: minor` | an issue that is barely noticeable and has little impact for most users, an issue that is hard to reproduce, an issue that might not end up being fixed or is expected it might sit in the backlog for a while, an issue with a very high effort / low reward value |

**features priority**
| Tag | Description |
| -------- | -------- |
| `priority F0: urgent` | Feature that has to be implemented & released ASAP for strong urgent reasons (likely a rare tag to use) |
| `priority F1: mandatory` | A feature the product must have, a feature that some other feature or section cannot be used without it |
| `priority F2: important` | a feature the app should have if possible, has high business value but the app can work without it |
| `priority F3: nice to have` | a feature the app could have but is not critical |
| `priority F4: maybe someday` | a feature that has currently low business value and potentialy high effort /reward ratio |

## Issues Prioritization Criteria

Issues are typically prioritized according to the following

1. type=bug and priority=`priority 0: blocker`
2. type=feature and priority=`priority F0: urgent`
3. type=bug and priority=`priority 1: high`
4. type=feature and priority=`priority F1: mandatory`
5. (type=bug and priority=`priority 2: medium`) or (type=feature=priority=`priority F2: important`)
5a. chat > wallet > general > onboarding > profile > node > timeline > browser > internal
5b. bug > feature
6. (type=bug and priority=`priority 3: low`) or (type=feature=priority=`priority F3: nice to have`)
6a. chat > wallet > general > onboarding > profile > node > timeline > browser > internal
6b. bug > feature
7. (type=bug and priority=`priority 4: minor`) or (type=feature=priority=`priority F4: maybe someday`)
7a. chat > wallet > general > onboarding > profile > node > timeline > browser > internal
bb. bug > feature
8. chat > wallet > general > onboarding > profile > node > timeline > browser > internal
9. bug > feature > refactor > chore > idea

priority field categorization

1. Urgent: `priority 0: blocker` or `priority F0: urgent`
2. Important: `priority 1: high` or `priority F1: mandatory`
3. Upcoming: `priority 2: medium` or `priority F2: important`
4. Low priority: `priority 3: low` or `priority F3: nice to have`
5. Someday: `priority 4: minor` or `priority F4: maybe someday`
6. Icebox: includes `priority 4: minor` or `priority F4: maybe someday` and issues that are blocked, chores, nice to haves etc..

## <a name="submit"></a> Submission Guidelines

### <a name="submit-issue"></a> Submitting an Issue

Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.

We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. In order to reproduce bugs, we will systematically ask you to provide steps to reproduce your issue.

You can file new issues by filling out our [new issue form](https://github.com/embarklabs/embark/issues/new/choose).

### Submitting a Pull Request (PR)
Before you submit your Pull Request (PR) consider the following guidelines:

1. Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.
2. Fork the repo.
3. Make your changes in a new git branch:

     git checkout -b my-fix-branch master

4. Create your patch
5. Commit your changes using a descriptive commit message that follows our
[commit message conventions](#commit). Adherence to these conventions
is necessary because release notes are automatically generated from these messages.

     git commit -a

Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.

6. Push your branch to GitHub:

    git push origin my-fix-branch

7. In GitHub, send a pull request to `master`

**All PRs need at least 2 approvals in order to be merged plus be tested**

Make sure you first add the desktop team as reviewers (search for `status-im/desktop-devs`)

As for the person that will test the PR:
- For a normal bug fix:
- Randmoly choose one of the two developpers assigned as reviewer to be the tester
- For a new feature, a refactor or a big bug fix that touches multiple sections:
- Assign a QA as a reviewer (search `status-im/desktop-qa`)

The PR can be merged once the PR has approvals from the two developpers and has the `tested` label added from the tester.

* If we suggest changes then:
* Make the required updates.
* Re-run the test suites to ensure tests are still passing.
* Rebase your branch and force push to your GitHub repository (this will update your Pull Request):

    git rebase master -i
    git push -f

8. Ensure that your PR description refers the issue that it is fixing with `Fixes #123`

That's it! Thank you for your contribution!

#### After your pull request is merged

After your pull request is merged, you can safely delete your branch and pull the changes
from the main (upstream) repository:

* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

    git push origin --delete my-fix-branch

* Check out the master branch:

    git checkout master -f

* Delete the local branch:

    git branch -D my-fix-branch

* Update your master with the latest upstream version:

    git pull --ff upstream master

## <a name="commit"></a> Commit Message Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to **more readable messages** that are easy to follow when looking through the **project history**. But also, we use the git commit messages to **generate the change log**.

### Commit Message Format
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
format that includes a **type**, a **scope** and a **subject**:

type(<Project>/<SCOPE>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The **header** is mandatory and the **scope** of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
to read on GitHub as well as in various git tools.

The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any.

Samples:

docs(changelog): update changelog to beta.5

fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

### Revert
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.

### Type
Must be one of the following:

* **build**: Changes that affect the build system or external dependencies
* **ci**: Changes to our CI configuration files and scripts
* **docs**: Documentation only changes
* **feat**: A new feature
* **fix**: A bug fix
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* **test**: Adding missing tests or correcting existing tests

### Scope
The scope should be the name of the area affected (as perceived by the person reading the changelog generated from commit messages.

The following is the list of supported scopes:

* **@desktop/wallet** - Affecting the wallet section
* **@desktop/chat** - Affecting the chat section
* **@desktop/<`module`>** - Desktop module
* **@nim-status/<`section`>** - Nim statussection, ie `@nim-status/chat`

There are currently a few exceptions to the "use package name" rule:

* **vendor**: used for changes that change the dependencies.
* **changelog**: used for updating the release notes in CHANGELOG.md
* none/empty string: useful for `style`, `test` and `refactor` changes that are done across all packages (e.g. `style: add missing semicolons`)

### Subject
The subject contains a succinct description of the change:

* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize the first letter
* no dot (.) at the end

## PRs

### Special tags for PRs

| Tag | Description |
| -------- | -------- |
| QA | Use this to indicate that this PR needs in-depth testing by a QA before being merged |
| testing | PR is undergoing testing by a QA |
| tested | PR is fully tested and ready to be merged |
| do not merge | Use this to indicate that this PR cannot be merged at this time, typically due to some dependency |
| experimental | Use this to indicate that this PR is testing an idea (usually a performance improvement) and is not clear if it will be merged or not |

### Workflow for PRs

1. After a PR is submitted, someone from the team will review your PR and ask for changes or mark as approved
2. In cases a PR was marked with the `QA` tag, a QA will test in depth. However **all PRs need an approval from a QA before being merged**
3. After a PR is approved by 2 developers and approved by 1 QA the owner of the PR should merge it.

### Long Term PRs & Draft PRs

Generally it is not encouraged for PRs to stay open for too long as they tend to lead to rebase conflicts, outdated functionality and generally they just tend to die. If a PR stays open for more than a month and is clearly stale it becomes under consideration to be closed.

### How to test the Pull Request?

1. make sure u understand what the PR does / changes. Feel free to ask questions , bug developer or designer or anyone, since it is your responsibility to drive the feature as QA, so don't be shy!
2. once all the information gathered, create tests in Test Rail. Creating test documentation (tests) is **mandatory**
3. test the functionality using the tests u added and provide a test run as a link posted with a comment to the corresponding PR. Please avoid the situation when u did some checks or verifications that are not listed in your test run. If u missed anything - be responsible and add it
4. do not create duplicates of tests, do not create granular tests (atomic checks). We are sticking to the strategy of using testing with use cases (or user scenarios) so try to be effiicent , cover as much functionality as u can with the less tests as possible (without losing quality)
5. dont be shy to remove tests, update tests , combine tests , but be rational
6. make sure u test not the happy path only, but edge cases , negatvie scenarios and think of where the functionality is present across the app, because the PRs can be containing lack of info, which means that even it is not stated in PRs, u still have to think and verify each and every possible corner of the app that is affected with the change
7. review the changed files on GH, it can be useful to understand what was affected
8. test not only the provided functionality but the regression around the affected area
9. test the upgrade of the recent released version (check [releases](https://github.com/status-im/status-desktop/releases)) to the PR version - there should not be any data loss or any other issues