CONTRIBUTING.md 8.14 KB
Newer Older
Benjamin Bouvier's avatar
Benjamin Bouvier committed
1
2
3
This file describes how to contribute **code** to Kresus. Note that many other
contributions are valuable and would be glady accepted in all of the following
domains: design, user interface, user experience, translations, documentation,
Benjamin Bouvier's avatar
Benjamin Bouvier committed
4
5
tutorials. If you want to get started with those, please head to our [community
forum](https://community.kresus.org). The only limit is the imagination!
Benjamin Bouvier's avatar
Benjamin Bouvier committed
6
7
8
9
10

These rules and recommendations can change over time, and should change. If you
have any ideas for improving them, please file an issue or open a merge
request!

11
12
# TL;DR

13
- Branch off `master`.
14
- One feature per commit.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
15
- In case of requests for changes, amend your commit.
16
17
18

# How to hack on Kresus

19
- First, install the app's dependencies:
Antoine's avatar
Antoine committed
20
```bash
21
yarn install
Antoine's avatar
Antoine committed
22
```
23
- Copy `config.example.ini` to `config.ini` and set values for your local
24
  development environment. See "setting up a database for development" below.
25
- Start development mode: `yarn dev`. This will automatically build the server
26
27
28
29
30
  and client files, spawn the main server on localhost:9876, (and reload it
  whenever a server source file is changed), spawn a client server on
  localhost:8080 and opens the index page on a browser (which gets reloaded
  every time a client file is touched).

31
If dev mode doesn't work, under Unix based operating systems (Linux, MacOS),
32
33
34
you might need to [increase the number of inotify
nodes](https://confluence.jetbrains.com/display/IDEADEV/Inotify+Watches+Limit).

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
## Setting up a database for development

In the `config.ini` file, you can set up a sqlite database quickly with the
following database configuration:

    [db]
    type=sqlite
    sqlite_path=/tmp/dev.sqlite

It is important that Postgres support is maintained too, so it is recommended
to try changes with Postgres before submitting the MR. It is possible to set up
a Docker instance of Postgres with the following command line:

```bash
docker run --rm --name kresus-postgres -p 5432:5432 -e POSTGRES_PASSWORD=kresusdev postgres
```

And then you can use the following settings in the configuration file:

    [db]
    type=postgres
    host=localhost
    port=5432
    username=postgres
    name=postgres
    password=kresusdev

Antoine's avatar
Antoine committed
62
63
64
65
66
67
68
69
70
71
72
73
# Running tests

A series of tests are shipped with the code to avoid regressions. They are
located in the `./tests` folder.
Some tests require a valid install of Weboob to work properly, some others do not.
For that, the weboob related tests are disabled if the environment variable
`KRESUS_WEBOOB_DIR` is not set. Some other tests are disabled if this
environment variable is set.
To ensure all the tests pass, you need to run the test command twice, once with
`KRESUS_WEBOOB_DIR` set, once without. For example:

```bash
74
75
yarn ci:test
KRESUS_WEBOOB_DIR=/path/to/weboob yarn ci:test
Antoine's avatar
Antoine committed
76
77
```

78
79
# About `package.json` file

Benjamin Bouvier's avatar
Benjamin Bouvier committed
80
81
82
We use the `package.json` file in a reproducible way, specifying the exact
version to use. Please make sure all version numbers are **exact** in
`package.json`, thus using no version ranges specifiers like `~`, `>` etc.
83

84
85
# About branches

86
- `master` contains all changes in the current development version, including
87
  some experimental features that could break in production.
88
- `builds` contains a stable version of the code for releases.
89
90
91

# How to contribute

Benjamin Bouvier's avatar
Benjamin Bouvier committed
92
93
94
- Please note that not every feature can make it into Kresus. New features add
  complexity and usually the maintenance burden is carried by the core team.
  Also, Kresus tries to limit its scope to doing one thing well.
95
- If you're thinking about a new feature, see if there's already an issue open
Benjamin Bouvier's avatar
Benjamin Bouvier committed
96
97
98
  about it (but don't sweat it too much if you can't find one!), or open one
  otherwise. This will ensure that everybody is on track for the feature and
  willing to have it in Kresus.
99
- One commit per feature.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
100
101
102
103
104
- Branch off the `master` branch.
- Rebase when you're close to landing, to make sure there's no [merge
  skew](https://bors.tech/essay/2017/02/02/pitch/) risk. We don't do merge
  commits, because they break bisection and add a lot of noise in the commit
  history.
105
106
- Test your code with `yarn ci`. This also runs linting and a few consistency
  checks.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
107
108
109
110
111
112
113
- For client changes, it is highly recommended to run extensive tests, and to
  note if there are tests known to fail. In particular, when touching a form,
  it's strongly advised to try to use invalid data, run it, close it, enter
  data and close it and re-open it, etc.
- We'll look at your MR and might ask for a few changes. In this case, use your
  best judgement to consider wheter it's smarter to create new commits or to
  amend existing ones. When the final result looks good, we may ask you to
Benjamin Bouvier's avatar
Benjamin Bouvier committed
114
115
116
117
118
119
120
121
  squash the WIP commits into a single one, to maintain the invariant of "one
  feature, one commit".

# Core team

- Core contributors: `nicofrand`, `ZeHiro`, `Phyks`. Core contributors can
  review and merge MRs, and have full power on the repository, including but
  not limited to push access on the `master` branch.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
122
123
124
- Module owner: `bnjbvr` (if alive). They get the last word and can veto the
  progression of a particular merge request, which should only happen in last
  resort if no cooperative solutions have been found otherwise.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
125
126
127
128
129
130
131
132

# Review and merge rules

- More than one person must have the commit accesses on `master`.
- All code changes must pass through the process of review. As a matter of
  fact, it is not allowed to push directly on the `master` branch. All changes
  must go through a merge request.
- All merge requests must be reviewed and approved by at least one core
133
  contributor before they can be considered for a merge. The marking of a merge
Benjamin Bouvier's avatar
Benjamin Bouvier committed
134
  request with the `ship-it` label indicates that a merge request can be merged
135
136
  by the author, once the remaining issues / remarks have been addressed; of
  course, if other questions arise, the author can ask for another round of
Benjamin Bouvier's avatar
Benjamin Bouvier committed
137
  review (and unmark the MR as `ship-it`).
Benjamin Bouvier's avatar
Benjamin Bouvier committed
138
139
140
141
142
- Merge requests shouldn't be merged no less than one day after they've been
  proposed, to make sure people have time to test them and think about all the
  possible implications they could have.
- Bug fixes can be merged without too much wait.
- New features or anything involving architecture discussions and design
Benjamin Bouvier's avatar
Benjamin Bouvier committed
143
  interactions should be reviewed and approved by the module owner.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
144
145
146
147
148
- If a review takes more than a few days, it is appropriate to gently ping the
  reviewer(s). Note that they might be busy in meat space. Not getting a review
  isn't a reason to merge any time sooner.
- Failing to respect these rules may result in losing the right to merge, after
  a first warning strike and a discussion between contributors.
149
150
151
152
153
154

# Release process

## Publish on git

- Update the version number in the package.json file on the `master` branch.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
155
- Checkout the `builds` branch and merge from `master` with `git checkout
Antoine's avatar
Antoine committed
156
  builds && git merge -X theirs master` (which will always take
Benjamin Bouvier's avatar
Benjamin Bouvier committed
157
  master changes).
158
- Run `yarn release`.
159
160
161
162
163
164
165
166
- Check `git status`, unstage unwanted changes, and commit with `Build;` in the
  commit message.
- Run `git tag 0.14.0` with the version number.
- Push the `builds` branch and the tag.

## Publish on npm

- Just after this on the same branch, run `npm publish`.
Antoine's avatar
Antoine committed
167
- Test npm release with `npm install --prefix /tmp kresus` and run Kresus from there.
168
169
170

## Publish on Docker hub

171
- Run `yarn docker:release` (ensure it doesn't use cached images).
172
173
- `docker tag bnjbvr/kresus:latest bnjbvr/kresus:0.14.0` with the right version
  number.
174
- `docker login` with your credentials
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
- `docker push bnjbvr/kresus`

## Website and demo

- Write a blog post for the release:
    - check commits.
    - don't talk too much about implementation details unless a lot of work has
      been done in a particular area, e.g. tests, migrating DB, etc.
    - give visibility to non-technical contributions too.
    - format the blog post so all images etc. are served locally
    - add Pelican metadata.
- Update the demo on demo.kresus.org with the docker image, make sure it still
  works.

## Extra communication

- Create social media messages for Mastodon / Twitter and publish them with a
  link to the blog post.
- Ideally, re-publish social media updates a few hours / days later.
- Let package maintainers know about the update, and try to give instructions
  to make it easier to ugprade their packages (ArchLinux / YNH).