Note: The default ITS GitLab runner is a shared resource and is subject to slowdowns during heavy usage.
You can run your own GitLab runner that is dedicated just to your group if you need to avoid processing delays.

CONTRIBUTING.markdown 3.28 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Contributing Issues
===================

To submit an [issue](https://gitlab.umich.edu/swmf_software/swmfpy/issues) please make sure to be very specific on the trouble you are having. If your issue is a bug make sure to paste this in your text and add to it as necessary:

- Problem:
- Error text:
- How to reproduce the error:
- Computer specs:

Once you fill out those you are ready to [submit an issue](https://gitlab.umich.edu/swmf_software/swmfpy/issues).

If your issue is a task or feature request, fill this out:

- Feature or task:
- Benefits:
- Where to start:

If you fill out those you are ready to [submit an issue](https://gitlab.umich.edu/swmf_software/swmfpy/issues).

Contributing Code
=================
Qusai Al Shidi's avatar
Qusai Al Shidi committed
23
24
25

Before submitting pull requests please make sure your code complies with the following.

Qusai Al Shidi's avatar
Qusai Al Shidi committed
26
27
28
29
30
Git etiquette
-------------

If you're planning on adding a feature (new function or class) then create your own branch,

31
```shell
32
$ git checkout -b my_new_feature
Qusai Al Shidi's avatar
Qusai Al Shidi committed
33
34
35
36
```

and start commiting there to test and work on. We will follow a [trunk-based development model](https://youtu.be/ykZbBD-CmP8). This means we will rapidly merge branches once you have something stable and continue with master branch. So make sure to push something stable instead of being in your feature branch for too long. I will try to address your pull request ASAP.

37
[![Trunk-based Development](http://img.youtube.com/vi/ykZbBD-CmP8/0.jpg)](https://www.youtube.com/watch?v=ykZbBD-CmP8 "Trunk-based Development")
38

Qusai Al Shidi's avatar
Qusai Al Shidi committed
39
40
41
42
43
Coding Style: PEP 8
-------------------

The style for your code must follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide. It would be helpful to use a linter like [pylint](https://pylint.org) to check whether your code is complying before submitting.

44
```shell
45
$ pylint somefile.py
Qusai Al Shidi's avatar
Qusai Al Shidi committed
46
47
48
49
50
51
52
```

Coding Standard
---------------

Please write readable code. Make sure your function names well describes your functions. Always include docstrings that use the [Google coding style](http://google.github.io/styleguide/pyguide.html#381-docstrings). The Google coding style guide is a good document to follow so I recommend reading it.

53
54
55
Metadata
--------

56
Include metadata if you made a new function or module. Name and email will suffice. Use the variable names `__author__` and `__email__` for modules and comments for functions that you add to someone else's module. For example:
57
58
59
60
61
62

mynewpackage.py:

```python
"""A new package for swmfpy
"""
63
__all__ = ['funcs', 'to', 'export']
64
65
__author__ = 'Rita Hayworth'
__email__ = 'rita@umich.edu'
66
67
68
69
70
```

Or for a function:
```python
def my_new_func(some_args):
71
72
73
74
75
    """my docstring
    """
    # Author: Diane Selwyn
    # Email:  diane@umich.edu

76
77
78
    # function body
```

79
80
81
82
83
84
There are helpful snippets for these:

- function $91
- class $92
- file $93

Qusai Al Shidi's avatar
Qusai Al Shidi committed
85
86
87
Dependencies
------------

88
If your code has dependencies that is large and uncommon (e.g. `tecplot`) then please import it in a new module.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
89

90
Then your functions will be in `swmfpy.tecplot` which has its own namespace.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
91

92
If it's a well known easy to find software like, for example, `spacepy` then we can discuss in a merge request whether swmfpy should depend on such module. Usually the answer is yes as `pip` does its job well :).
Qusai Al Shidi's avatar
Qusai Al Shidi committed
93
94
95
96
97

Modules
-------

If you want to create a new module make sure what you're trying to do can't just fit in the modules already made.