You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Welcome and thank you for your interest in contributing to the project. This document aims to describe the preferred workflow
4
+
5
+
## Contributing
6
+
7
+
For small bugs, typos, documentation improvements, and minor changes - follow the steps in the [Working on topic branches](#working-on-topic-branches) section below to create a Pull Request.
8
+
9
+
For large changes, or new feature requests - please start an **Ideas** discussion first. Explain your idea, include some reasoning, perhaps some implementation ideas.
10
+
11
+
## Setup
12
+
13
+
> Credit to the [QuantConnect Lean project](https://github.com/QuantConnect/Lean), where most of these instructions originated
14
+
15
+
* Set up a [GitHub](https://github.com/) account
16
+
*[Fork](https://help.github.com/articles/fork-a-repo/) the [repository](https://github.com/robcarver17/pysystemtrade) of the project
The *upstream* remote links your fork of the project with the original
31
+
32
+
## Keeping your repo up to date
33
+
34
+
Now that you've defined the upstream branch, you can refresh your local copy with the following commands:
35
+
36
+
```bash
37
+
$ git checkout develop
38
+
$ git pull
39
+
```
40
+
41
+
This will checkout your local develop branch and then merge changes in from upstream
42
+
43
+
## Branching model
44
+
45
+
If you are not familiar with git branches, please read this [guide](https://www.atlassian.com/git/tutorials/using-branches/). Our branching model is based on the one outlined [here](https://nvie.com/posts/a-successful-git-branching-model/)
46
+
47
+
The following names will be used to differentiate between the different repositories:
48
+
49
+
***upstream** - The 'official' pysystemtrade [repository](https://github.com/robcarver17/pysystemtrade.git) (what is on Rob's GitHub account)
50
+
***origin** - Your fork of the official repository on GitHub (what is on your GitHub account)
51
+
***local** - This will be your local clone of **origin** (what is on your computer)
52
+
53
+
As a **contributor** you will push your completed **local** topic branch to **origin**. As a **contributor** you will pull your updates from **upstream**. Assuming the change is accepted, a **collaborator** will merge branches from a **contributor** into **upstream**.
54
+
55
+
## Primary branches
56
+
57
+
The upstream repository has two branches:
58
+
59
+
***upstream/master** - Stable releases
60
+
***upstream/develop** - where development work happens
61
+
62
+
From time to time, when **develop** is stable, everything on **develop** gets merged into **master**, and that becomes the new stable version.
63
+
64
+
## Topic branches
65
+
66
+
Topic branches are for contributors to develop bug fixes and new features so that they can be easily merged to **develop**. They must follow a few simple rules for consistency:
67
+
68
+
* Must branch off from **develop**
69
+
* Must be merged back into **develop**
70
+
* Ideally, should have the GitHub issue number in the branch name
71
+
72
+
Topic branches should exist in your **local** and **origin** repositories only. Submitting a pull request will request a merge from your topic branch to the **upstream/develop** branch.
73
+
74
+
## Working on topic branches
75
+
76
+
First create a new branch for the work you'd like to perform. When naming your branch, please use the following convention: `bug-<issue#>-<description>` or `feature-<issue#>-<description>`:
77
+
78
+
```bash
79
+
$ git checkout -b bug-123-short-issue-description
80
+
Switched to a new branch 'bug-123-short-issue-description'
81
+
```
82
+
83
+
Now perform some work and commit changes. Always review your changes before committing
84
+
85
+
```bash
86
+
$ git status
87
+
$ git diff
88
+
$ git add --all
89
+
$ git commit
90
+
```
91
+
92
+
You can push your changes to your fork's develop branch using:
93
+
94
+
```bash
95
+
$ git push origin develop
96
+
```
97
+
98
+
When committing, be sure to follow [best practices](https://github.com/erlang/otp/wiki/Writing-good-commit-messages) writing good commit descriptions.
99
+
100
+
After performing some work you'll want to merge in changes (if any) from the **upstream/develop**. You can use the following two commands in order to assist upstream merging:
The `git fetch upstream` command will download the **upstream** repository to your computer but not merge it. The `merge upstream/develop bug-123-short-issue-description` command will [merge](https://www.atlassian.com/git/tutorials/using-branches/git-merge) your changes on top of **upstream/develop**. This will make the review process easier for **collaborators**.
108
+
109
+
If you need to merge changes in after pushing your branch to **origin**, use the following:
110
+
111
+
```bash
112
+
$ git pull upstream/develop
113
+
```
114
+
115
+
When topic branches are finished and ready for review, they should be pushed back to **origin**.
Now you're ready to send a [pull request](https://help.github.com/articles/using-pull-requests/) from this branch to **upstream/develop** and update the GitHub issue tracker to let a collaborator know that your branch is ready to be reviewed and merged. If extra changes are required as part of the review process, make those changes on the topic branch and re-push. First re-checkout the topic branch you made your original changes on:
124
+
125
+
```bash
126
+
$ git checkout bug-123-short-issue-description
127
+
```
128
+
129
+
Now make responses to the review comments, commit, and re-push your changes:
130
+
131
+
```bash
132
+
$ git add --all
133
+
$ git commit
134
+
$ git push
135
+
```
3
136
4
137
## Unit tests
5
-
This project has a few unit tests. They get run automatically when any PR is
6
-
submitted. You'll see the result of the run in the PR page. To run the tests
7
-
yourself locally, before submitting, you'll need `pytest` installed. Then run:
138
+
This project has a few unit tests. They get run automatically when any PR is submitted. You'll see the result of the run in the PR page. To run the tests yourself locally, before submitting, you'll need `pytest` installed. Then run:
8
139
```
9
140
pytest
10
141
```
@@ -19,38 +150,34 @@ To run all the tests except one module, use the `--ignore` flag
Some tests are marked as `@pytest.mark.slow` because they take a long time. These
23
-
run automatically every evening. If you want to run them locally, pass
24
-
the `--runslow` flag
153
+
Some tests are marked as `@pytest.mark.slow` because they take a long time. These run automatically every evening. If you want to run them locally, pass the `--runslow` flag
25
154
```
26
155
pytest --runslow
27
156
```
28
157
29
158
30
159
## Lint / Black
31
160
32
-
This project keeps its code pretty with
33
-
[Black](https://black.readthedocs.io/en/stable/). Black gets automatically run
34
-
over any PRs, and the PR won't be merged if it fails. To clean your code
35
-
submission manually you'll need Black installed, instructions
36
-
[here](https://black.readthedocs.io/en/stable/getting_started.html). Then
37
-
run:
161
+
This project keeps its code pretty with [Black](https://black.readthedocs.io/en/stable/). Black gets automatically run over any PRs, and the PR won't be merged if it fails. To clean your code submission manually you'll need Black installed, instructions [here](https://black.readthedocs.io/en/stable/getting_started.html). Then run:
162
+
```
163
+
black .
164
+
```
165
+
166
+
If you have a virtual environment (venv), you will want to tell Black to ignore that. So if your venv is named `.venv`, the command would be:
167
+
38
168
```
39
-
black path/to/module.py
169
+
black . --exclude '/.venv\/.+/'
40
170
```
41
171
42
-
Or, get your IDE or editor to automatically re-format files as you save. Configuration
Or, get your IDE or editor to automatically re-format files as you save. Configuration instructions [here](https://black.readthedocs.io/en/stable/integrations/editors.html)
44
173
45
174
Note for pycharm users: The blackd plugin requires a blackd daemon to be running; add it to your crontab.
46
175
47
-
Or, configure your local git install to automatically check and fix your code
Or, configure your local git install to automatically check and fix your code as you commit. Configuration instructions [here](https://black.readthedocs.io/en/stable/integrations/source_version_control.html)
50
177
51
178
### Black version
52
179
53
-
Black needs to be consistent between the version running in the CI build and your local environment. To check the currently used version, see the `[tool.black]` section of the project TOML file(https://github.com/robcarver17/pysystemtrade/blob/master/pyproject.toml)
180
+
Black needs to be consistent between the version running in the CI build and your local environment. To check the currently used version, see the `[tool.black]` section of the project [TOML file](https://github.com/robcarver17/pysystemtrade/blob/develop/pyproject.toml)
54
181
55
182
## General code guidelines (INCOMPLETE)
56
183
@@ -75,7 +202,7 @@ In general, we try and follow the original texts: [PEP 8](https://peps.python.or
75
202
76
203
### Error handling
77
204
78
-
- Production code should not throw an error unless things are completely unrecoverable; if it does throw an error it must also log.critical which will email the user
205
+
- Production code should not throw an error unless things are completely unrecoverable; if it does throw an error it must also `log.critical()` which will email the user (with the default production log config)
79
206
80
207
81
208
### Caching
@@ -85,7 +212,6 @@ FIXME This is a bit of a mess - Update when a unified cache system setup
85
212
86
213
### Testing
87
214
88
-
Doc tests should be removed from class methods, since they often require a lot of setup, and make the code harder to read. Unit tests are preferable.
89
-
Doc tests make more sense for seperate, standalone, functions. This is especially the case when they can be used to quickly demonstrate how a function works.
215
+
Doc tests should be removed from class methods, since they often require a lot of setup, and make the code harder to read. Unit tests are preferable. Doc tests make more sense for separate, standalone, functions. This is especially the case when they can be used to quickly demonstrate how a function works.
0 commit comments