Skip to content

Commit fa0d0ad

Browse files
carandraugcarandraug
committed
doc: add more contributor guidelines instructions.
Most of the stuff in contributor instructions were targeted at maintainers. This change moves those to a new section of the documentation, and adds fresh instructions with coding guidelines, how to report an issue, etc.
1 parent 9c0063c commit fa0d0ad

File tree

2 files changed

+139
-62
lines changed

2 files changed

+139
-62
lines changed

‎doc/hacking.rst‎

Lines changed: 138 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. Copyright (C) 2017 David Pinto <david.pinto@bioch.ox.ac.uk>
1+
.. Copyright (C) 2019 David Miguel Susano Pinto <david.pinto@bioch.ox.ac.uk>
22
33
Permission is granted to copy, distribute and/or modify this
44
document under the terms of the GNU Free Documentation License,
@@ -7,89 +7,165 @@
77
no Back-Cover Texts. A copy of the license is included in the
88
section entitled "GNU Free Documentation License".
99
10-
Contributor instructions
11-
************************
10+
Contributing
11+
************
1212

13-
Tests
14-
=====
13+
This documentation is for people who want to contribute code to the
14+
project, whether fixing a small bug, adding support for a new device,
15+
or even discussing a completely new device type.
1516

16-
Microscope testsuite can be ran with setuptools, like so::
1717

18-
python setup.py test
18+
In short
19+
========
1920

20-
All test units, as well as other tools for testing purposes, are part
21-
of the :py:mod:`microscope.testsuite` package.
21+
- Open new issues. Do not create pull requests.
22+
- Open a new issue even if you already have a commit made. Even if it
23+
is about adding support for a new device.
24+
- Coding style is `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_
25+
- Development sources at
26+
`<https://github.com/MicronOxford/microscope>`_
27+
- Bug tracker at `<https://github.com/MicronOxford/microscope/issues>`_
28+
29+
30+
Reporting issues
31+
================
32+
33+
We use the github issue tracker at
34+
`<https://github.com/MicronOxford/microscope/issues>`_. When
35+
reporting an issue, please include as much information as you can
36+
from:
37+
38+
- Steps to reproduce issue
39+
Include information so that we can try it ourselves. Don't just
40+
say "camera fails when setting exposure time". Instead, include
41+
the code to reproduce the issue and the error message.
42+
43+
- Operating system
44+
MacOS 10.15, Ubuntu 18.04, Windows 7, Windows 10, etc...
45+
46+
- Python version
47+
Also include the python minor version number, i.e, Python 3.7.3 or
48+
3.6.2. On command line, this is the output of `python --version`.
49+
50+
- Device, SDK, and firmware information
51+
Include the device model, revision number, and serial number.
52+
Also include the firmware and the device SDK version number.
53+
54+
- PyRO version
55+
If the issue only happens in the network, please also include the
56+
version of the PyRO package.
57+
58+
59+
Requesting support for new device
60+
=================================
61+
62+
To request support for a new device, or even to support for a feature
63+
of an already supported device, open a new issue on the `issue tracker
64+
<https://github.com/MicronOxford/microscope/issues>`_.
65+
66+
If there's already an open issue requesting the same, please leave a
67+
comment so that we know more people want it.
68+
69+
70+
Fixing an issue
71+
===============
2272

73+
To fix an issue, including adding support for a new device, please do
74+
the following:
2375

24-
Documentation
25-
=============
76+
- Open a new issue (if not already opened)
77+
- On the commit message, refer to the issue number
78+
- Comment on the issue what branch or commit to pull to fix it.
2679

27-
Documentation is inline within docstrings and must follow the `Google
28-
Python docstrings format
29-
<http://google.github.io/styleguide/pyguide.html?showone=Comments#Comments>`_.
30-
These will be parsed by `Sphinx's Napoleon extension
31-
<http://www.sphinx-doc.org/en/stable/ext/napoleon.html>`_ so `its own
32-
examples
33-
<http://www.sphinx-doc.org/en/stable/ext/example_google.html>`_. This
34-
can be generated like so::
80+
Why the non-standard procedure?
81+
-------------------------------
3582

36-
python setup.py build_sphinx
83+
This procedure to fix an issue is not very standard on github
84+
projects. However, it prevents spreading the discussion of the issue
85+
over multiple pages and enables one to find that discussion from the
86+
git history.
3787

3888

39-
Versioning
40-
==========
89+
Coding standards
90+
================
4191

42-
We use the style `major.minor.patch` for releases and haven't yet had
43-
to deal with rc.
92+
Code style
93+
----------
4494

45-
In between releases and snapshots, we use the `dev` as a local version
46-
identifiers as per `PEP 440
47-
<https://www.python.org/dev/peps/pep-0440/>`_ so a version string
48-
`0.0.1+dev` is the release `0.0.1` plus development changes on top of
49-
it (and not development release for an upcoming `0.0.1`). With
50-
examples:
95+
For code formatting use `PEP 8
96+
<https://www.python.org/dev/peps/pep-0008/>`_.
5197

52-
* `0.0.1` - major version 0, minor version 0, patch version 1
98+
Docstrings
99+
----------
53100

54-
* `0.0.1+dev` - not a public release. A development build, probably
55-
from VCS sources, sometime *after* release `0.0.1`. Note the use of
56-
`+` which marks `dev` as a local version identifier.
101+
The whole API section of the documentation is generated from the
102+
inlined docstrings. It requires the `Google Python docstrings format
103+
<https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`_.
104+
It looks like this::
57105

58-
* `0.0.1.dev1` - we do not do this. PEP 440 states this would be the
59-
first development public release *before* `0.0.1`. We use `+dev`
60-
which are local version and not public releases. This is only
61-
mentioned here to avoid confusion for people used to that style.
62106

107+
def func(arg1, arg2):
108+
"""One-line summary.
63109

64-
Steps to make a release
65-
=======================
110+
Extended description of function.
66111

67-
#. Change version number on `setup.py` and commit that change only.
68-
Note that we use `release-N` for tag and not `v.N` to allow one day
69-
for snapshot releases with tags such as `snapshot-N`::
112+
Args:
113+
arg1 (int): Description of arg1. This can be a multi-line
114+
description, no problem.
115+
arg2 (str): Description of arg2.
70116

71-
VERSION=$(python setup.py --version)
72-
COMMIT=$(git rev-parse HEAD | cut -c1-12)
73-
git commit -m "maint: release $VERSION" setup.py
74-
git tag -s -u $GPGKEY -m \
75-
"Added tag release-$VERSION for commit $COMMIT" release-$VERSION
117+
Returns:
118+
bool: Description of return value
119+
"""
120+
return True
76121

77-
#. Build a source distribution from an export (in case of any non
78-
committed or ignored files)::
122+
Commit messages
123+
---------------
79124

80-
rm -rf target/
81-
git archive --format=tar --prefix="target/" HEAD | tar -x
82-
cd target/
83-
python setup.py sdist --formats=gztar
125+
The first line of the commit message have a one-line summary of the
126+
change. This needs to mention the class, function, or module where
127+
relevant changes happen. If there's an associated issue number, make
128+
reference to it. If it is a "fixup" commit, make reference to it.
129+
Some examples for changes:
130+
131+
- limited to a method function::
132+
133+
TheClassName.initialize: fix for firmware older than Y (issue #98)
134+
135+
- effecting multiple methods in a class::
136+
137+
TheClassName: add support for very fancy feature (issue #99)
138+
139+
- fixing a typo or obvious mistake on a previous commit::
140+
141+
AndorAtmcd: pass index to super (fixup a16bef042a41)
142+
143+
- documentation only::
144+
145+
doc: add example for multiple cameras with hardware triggering
146+
147+
148+
Test suite
149+
----------
150+
151+
Most of Python Microscope is about controlling very specific hardware
152+
and there are no realist mocks of such hardware. Still, some parts
153+
can be tested with::
154+
155+
python setup.py test
156+
157+
All test units, as well as other tools for testing purposes, are part
158+
of the :py:mod:`microscope.testsuite` package.
84159

85-
#. Upload and sign distribution::
160+
If your changes do not actually change a specific device, please also
161+
include a test unit.
86162

87-
twine upload -r pypi -s -i $GPGKEY target/dist/microscope-X.tar.gz
88163

89-
#. Add `+dev` to version string::
164+
Copyright
165+
=========
90166

91-
sed -i "s,\(^project_version = '[^+]*\)',\1+dev'," setup.py
92-
git commit setup.py -m \
93-
"maint: set version to $VERSION+dev after $VERSION release."
94-
git push upstream master
95-
git push upstream release-$VERSION
167+
We do not request that copyright is assigned to us, you will remain
168+
the copyright holder of any contribution made. However, please ensure
169+
that you are the copyright holder. Depending on your contract, the
170+
copyright holder might be your employer or university, even if you are
171+
a student. Ask your employer or PhD supervisor.

‎doc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Python Microscope
2020
supported-devices
2121
API <api/modules>
2222
hacking
23+
maintainer
2324
history
2425
contributors
2526

0 commit comments

Comments
 (0)