CONTRIBUTING.md 3.25 KB
Newer Older
Marco Govoni's avatar
Marco Govoni committed
1 2
# Contributing to the source

Marco Govoni's avatar
Marco Govoni committed
3
Contributions are welcomed via merge requests. Contact the **WEST** developers before starting work to ensure it meshes well with the planned development direction and
Marco Govoni's avatar
Marco Govoni committed
4
standards set for the project.
Marco Govoni's avatar
Marco Govoni committed
5

Marco Govoni's avatar
Marco Govoni committed
6 7
## Version control

Marco Govoni's avatar
Marco Govoni committed
8
All changes in a pull request should be closely related. Multiple change sets that are loosely coupled should be proposed in separate pull requests. Use a consistent style for writing code.
Marco Govoni's avatar
Marco Govoni committed
9 10

## Features
Marco Govoni's avatar
Marco Govoni committed
11

Marco Govoni's avatar
Marco Govoni committed
12
New features should be applicable to a variety of use-cases. The **WEST** developers can assist you in designing flexible interfaces.
Marco Govoni's avatar
Marco Govoni committed
13

Marco Govoni's avatar
Marco Govoni committed
14
## Testing
Marco Govoni's avatar
Marco Govoni committed
15

Marco Govoni's avatar
Marco Govoni committed
16
Add tests for all new functionality.
Marco Govoni's avatar
Marco Govoni committed
17

Marco Govoni's avatar
Marco Govoni committed
18 19
## Release

Marco Govoni's avatar
Marco Govoni committed
20
We use [semantic versioning](https://semver.org/), i.e. version labels have the form v`<major>`.`<minor>`.`<patch>`
Marco Govoni's avatar
Marco Govoni committed
21

Marco Govoni's avatar
Marco Govoni committed
22 23 24
 - Patch release: v0.0.0 to v0.0.1, only bug fixes
 - Minor release: v0.0.0 to v0.1.0, bug fixes and new features that maintain backwards compatibility
 - Major release: v0.0.0 to v1.0.0, bug fixes and new features that break backwards compatibility
Marco Govoni's avatar
Marco Govoni committed
25 26

# Contributing to the documentation
Marco Govoni's avatar
Marco Govoni committed
27

Marco Govoni's avatar
Marco Govoni committed
28 29
Comment complex sections of code so that other developers can understand them.
Add demonstrations of new functionality, e.g. using Jupyter notebooks.
Marco Govoni's avatar
Marco Govoni committed
30

Marco Govoni's avatar
Marco Govoni committed
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
---

# Developer's workflow

  1. Clone the repository to your local machine
```bash
  $ git clone <http-git-repo>
```

  2. Use the following to see all the available branches and which branch you are on:
```bash 
  $ git branch -a
```

  3. Create a branch for the feature you are going to work on. Internal users should branch from the `develop` branch.
```bash
  $ git checkout -b <myfeature>
```

  4. Make changes to the repository:
```bash 
  $ touch <file>
```

  5. Check which files have been changed in your local directory by
```bash 
  $ git status
```

  6. Commit your changes and push to the remote repository:
```bash 
  $ git add <file>
  $ git commit -m "explain your modification"
  $ git push origin <myfeature>
```

  7. (Optional) Check commit history by
```bash  
  $ git log
```

  8. Then create a merge request on the gitlab website that hosts the remote repository:

  9. You can do one of the following after the merge request has been approved:
     - Delete the branch `myfeature`
     - Keep the original branch and keep working on it

## Often-countered scenarios

  1. When you want to add another feature, create a new branch for the new feature, e.g. `another_feature`, branching from the latest `develop` branch.  

  First switch to the `develop` branch:
```bash 
  $ git checkout develop
```
  Then update the local `develop` branch to include changes to the remote:
```bash 
  $ git pull origin develop
```
  Then create your new branch:
```bash 
  $ git branch -b <another_feature>
```
  Then repeat #4-#9 above.

  2. Suppose you are working on your feature branch and other people have changed the `develop` branch in the remote repository after you created your `myfeature` branch, you need to merge the `develop` branch into your `myfeature` branch before submitting a merge request.

  To merge the `develop` branch into your `myfeature` branch, you need checkout your `myfeature` branch.
```bash 
  $ git checkout <myfeature>
```
  Then do the following to merge the `develop` branch into the branch you are on it
```bash 
  $ git pull origin develop
```
  Then do #6-#9 above.