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 2.54 KB
Newer Older
Qusai Al Shidi's avatar
Qusai Al Shidi committed
1
2
3
4
5
Contributing
============

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

Qusai Al Shidi's avatar
Qusai Al Shidi committed
6
7
8
9
10
11
12
13
14
15
16
Git etiquette
-------------

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

```bash
git checkout -b my_new_feature
```

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.

17
18
19
20
<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/ykZbBD-CmP8" frameborder="0" allowfullscreen="true"> </iframe>
</figure>

Qusai Al Shidi's avatar
Qusai Al Shidi committed
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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.

```bash
pylint somefile.py
```

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.

35
36
37
Metadata
--------

38
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:
39
40
41
42
43
44

mynewpackage.py:

```python
"""A new package for swmfpy
"""
45
__all__ = ['funcs', 'to', 'export']
46
47
__author__ = 'Rita Hayworth'
__email__ = 'rita@umich.edu'
48
49
50
51
52
```

Or for a function:
```python
def my_new_func(some_args):
53
54
55
56
57
    """my docstring
    """
    # Author: Diane Selwyn
    # Email:  diane@umich.edu

58
59
60
    # function body
```

Qusai Al Shidi's avatar
Qusai Al Shidi committed
61
62
63
Dependencies
------------

64
If your code has dependencies that is large and uncommon (e.g. SpacePy) then please import it in the function and be explicit about the dependencies. For example you may create a function:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
65

66
67
68
69
70
71
```python
def func_with_dependency():
	"""Func does this.

	Depends on spacepy. Try `pip install -U spacepy`
	"""
Qusai Al Shidi's avatar
Qusai Al Shidi committed
72
	import spacepy
73
	# Function body
Qusai Al Shidi's avatar
Qusai Al Shidi committed
74
75
76
77
78
79
80
81
```

Then your functions will be in swmfpy.spacepy which has its own namespace.

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.