Skip to content

Commit b2abfba

Browse files
MarilythMarilyth
committed
Restructure development.rst
1 parent 17cffa9 commit b2abfba

1 file changed

Lines changed: 90 additions & 99 deletions

File tree

‎docs/development.rst‎

Lines changed: 90 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,68 @@
11
.. _development:
22

3+
===========
4+
Development
5+
===========
6+
7+
This chapter will get you started with MSS development.
8+
9+
MSS is written in Python.
10+
11+
Once a stable release is published we do only bug fixes in stable and release regulary
12+
new minor versions. If a fix needs a API change or it is likly more a new feature you have
13+
to make a pull request to the develop branch. Documentation of changes is done by using our
14+
`issue tracker <https://github.com/Open-MSS/MSS/issues>`_.
15+
16+
When it is ready the developer version becomes the next stable.
17+
18+
19+
The stable version of MSS is tracked on `BLACK DUCK Open Hub <https://www.openhub.net/p/mss>`_
20+
21+
22+
Style guide
23+
~~~~~~~~~~~~~~~~
24+
25+
We generally follow flake8, with 120 columns instead of 79.
26+
27+
Output and Logging
28+
~~~~~~~~~~~~~~~~~~~~~~~~~
29+
30+
When writing logger calls, always use correct log level (debug only for debugging, info for informative messages,
31+
warning for warnings, error for errors, critical for critical errors/states).
32+
33+
Setting Up a Local Environment
34+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35+
36+
Requirements
37+
------------
338

439
1. System requirements
540

641
| Any system with basic configuration.
742
| Operating System : Any (Windows / Linux / Mac).
843
944
2. Software requirement
45+
1046
| Python
1147
| `Additional Requirements <https://github.com/Open-MSS/MSS/blob/develop/requirements.d/development.txt>`_
1248
1349

1450
3. Skill set
51+
1552
| Knowledge of git & github
1653
| python
1754
18-
============================
19-
Setting Up local Environement
20-
============================
21-
22-
============================
2355
Forking the Repo
24-
============================
56+
----------------
57+
2558
1. Firstly you have to make your own copy of project. For that you have to fork the repository. You can find the fork button on the top-right side of the browser window.
2659

2760
2. Kindly wait till it gets forked.
2861

2962
3. After that copy will look like *<your-user-name>/MSS* forked from *Open-MSS/MSS*.
3063

31-
============================
3264
Cloning the Repo
33-
============================
65+
----------------
3466

3567
1. Now you have your own copy of project. Here you have to start your work.
3668

@@ -46,9 +78,10 @@ Cloning the Repo
4678

4779
or simply head over here for `cloning a repository <https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository>`_
4880

49-
============================
50-
Setting up remote :
51-
============================
81+
7. Add the path of your local cloned mss directory to $PYTHONPATH.
82+
83+
Setting up a git remote
84+
-----------------------
5285

5386
1. Now you have to set up remote repositories
5487

@@ -74,64 +107,11 @@ Setting up remote :
74107

75108
upstream ``https://github.com/Open-MSS/MSS.git`` (push)
76109

77-
78-
============================
79-
How to Report Bugs:
80-
============================
81-
Please open a new issue in the appropriate GitHub repository `here <https://github.com/Open-MSS/MSS/issues/new>`_ with steps to reproduce the problem you're experiencing.
82-
83-
Be sure to include as much information including screenshots, text output, and both your expected and actual results.
84-
85-
============================
86-
How to Request Enhancements:
87-
============================
88-
First, please refer to the applicable `GitHub repository <https://github.com/Open-MSS/MSS>`_ and search `the repository's GitHub issues <https://github.com/Open-MSS/MSS/issues>`_ to make sure your idea has not been (or is not still) considered.
89-
90-
Then, please `create a new issue <https://github.com/Open-MSS/MSS/issues/new>`_ in the GitHub repository describing your enhancement.
91-
92-
Be sure to include as much detail as possible including step-by-step descriptions, specific examples, screenshots or mockups, and reasoning for why the enhancement might be worthwhile.
93-
94-
============================
95-
Development
96-
============================
97-
98-
This chapter will get you started with MSS development.
99-
100-
MSS is written in Python.
101-
102-
Once a stable release is published we do only bug fixes in stable and release regulary
103-
new minor versions. If a fix needs a API change or it is likly more a new feature you have
104-
to make a pull request to the develop branch. Documentation of changes is done by using our
105-
`issue tracker <https://github.com/Open-MSS/MSS/issues>`_.
106-
107-
When it is ready the developer version becomes the next stable.
108-
109-
110-
The stable version of MSS is tracked on `BLACK DUCK Open Hub <https://www.openhub.net/p/mss>`_
111-
112-
113-
Style guide
114-
~~~~~~~~~~~~~~~~
115-
116-
We generally follow flake8, with 120 columns instead of 79.
117-
118-
Output and Logging
119-
~~~~~~~~~~~~~~~~~~~~~~~~~
120-
121-
When writing logger calls, always use correct log level (debug only for debugging, info for informative messages,
122-
warning for warnings, error for errors, critical for critical errors/states).
123-
124-
Setup a development environment
125-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126-
127-
If you want to contribute make a fork on github of `MSS <https://github.com/Open-MSS/MSS>`_.
128-
129-
In the mss package is some demodata included. The default where this is stored is $HOME/mss. Your clone of the
130-
MSS repository needs a different folder, e.g. workspace/mss. Avoid to mix data and source.
110+
Installing dependencies
111+
-----------------------
131112

132113
MSS is based on the software of the conda-forge channel located, so we have to add this channel to the default::
133114

134-
135115
$ conda config --add channels conda-forge
136116

137117
Your content of the .condarc config file should have conda-forge on top::
@@ -150,21 +130,49 @@ Create an environment and install the whole mss package dependencies then remove
150130
You can also use conda to install mss, but mamba is a way faster.
151131
Compare versions used in the meta.yaml between stable and develop branch and apply needed changes.
152132

153-
Add the path of your local cloned mss directory to $PYTHONPATH.
133+
Pushing your changes
134+
--------------------
154135

155-
For developer we provide additional packages for running tests, activate your env and run::
136+
1. Now you have made the changes, tested them and built them. So now it's time to push them.
137+
2. Goto your terminal and type git status and hit enter, this will show your changes from the files
138+
3. Then type in git add and hit enter, this will add all the files to staging area
139+
4. Commit the changes by ``git commit -m "<message-describing-your-change>"`` and hit enter.
140+
5. Now push your branch to your fork by ``git push origin <your-branch-name>`` and hit enter.
156141

157-
$ mamba install --file requirements.d/development.txt
158142

159-
On linux install the `conda package pyvirtualdisplay` and `xvfb` from your linux package manager.
160-
This is used to run tests on a virtual display.
161-
If you don't want tests redirected to the xvfb display just setup an environment variable::
143+
Creating a pull request
144+
-----------------------
162145

163-
$ export TESTS_VISIBLE=TRUE
146+
By this time you can see a message on your github fork as your fork is ahead of Open-MSS:develop by <number> of commits and also you can see a button called Compare and pull request.
147+
148+
Click on Compare and pull request button.
149+
150+
You will see a template.
151+
152+
Fill out the template completely by describing your change, cause of change, issue getting fixed etc.
153+
154+
After filling the template completely click on Pull request
164155

156+
How to Report Bugs
157+
~~~~~~~~~~~~~~~~~~
158+
159+
Please open a new issue in the appropriate GitHub repository `here <https://github.com/Open-MSS/MSS/issues/new>`_ with steps to reproduce the problem you're experiencing.
160+
161+
Be sure to include as much information including screenshots, text output, and both your expected and actual results.
162+
163+
How to Request Enhancements
164+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
165+
166+
First, please refer to the applicable `GitHub repository <https://github.com/Open-MSS/MSS>`_ and search `the repository's GitHub issues <https://github.com/Open-MSS/MSS/issues>`_ to make sure your idea has not been (or is not still) considered.
167+
168+
Then, please `create a new issue <https://github.com/Open-MSS/MSS/issues/new>`_ in the GitHub repository describing your enhancement.
169+
170+
Be sure to include as much detail as possible including step-by-step descriptions, specific examples, screenshots or mockups, and reasoning for why the enhancement might be worthwhile.
165171

166172
Setup demodata
167173
~~~~~~~~~~~~~~
174+
In the mss package is some demodata included. The default where this is stored is $HOME/mss. Your clone of the
175+
MSS repository needs a different folder, e.g. workspace/mss. Avoid to mix data and source.
168176

169177
:ref:`demodata` is provided by executing::
170178

@@ -196,6 +204,15 @@ Now you can use the MSS desktop application to connect to it using the Mscolab w
196204

197205
Running tests
198206
~~~~~~~~~~~~~~~~~~~
207+
For developers we provide additional packages for running tests, activate your env and run::
208+
209+
$ mamba install --file requirements.d/development.txt
210+
211+
On linux install the `conda package pyvirtualdisplay` and `xvfb` from your linux package manager.
212+
This is used to run tests on a virtual display.
213+
If you don't want tests redirected to the xvfb display just setup an environment variable::
214+
215+
$ export TESTS_VISIBLE=TRUE
199216

200217
We have implemented demodata as data base for testing. On first call of pytest a set of demodata becomes stored
201218
in a /tmp/mss* folder. If you have installed gitpython a postfix of the revision head is added.
@@ -347,29 +364,3 @@ Publish on Conda Forge
347364
* rerender the feedstock by conda smithy
348365
* send a pull request
349366
* maintainer will merge if there is no error
350-
351-
352-
============================
353-
Pushing your changes:
354-
============================
355-
356-
1. Now you have made the changes, tested them and built them. So now it's time to push them.
357-
2. Goto your terminal and type git status and hit enter, this will show your changes from the files
358-
3. Then type in git add and hit enter, this will add all the files to staging area
359-
4. Commit the changes by ``git commit -m "<message-describing-your-change>"`` and hit enter.
360-
5. Now push your branch to your fork by ``git push origin <your-branch-name>`` and hit enter.
361-
362-
363-
============================
364-
Creating a pull request:
365-
============================
366-
By this time you can see a message on your github fork as your fork is ahead of Open-MSS:develop by <number> of commits and also you can see a button called Compare and pull request.
367-
368-
Click on Compare and pull request button.
369-
370-
You will see a template.
371-
372-
Fill out the template completely by describing your change, cause of change, issue getting fixed etc.
373-
374-
After filling the template completely click on Pull request
375-

0 commit comments

Comments
 (0)