developers.md 5.64 KB
Newer Older
1
2
Developer notes
===============
3
4
This document briefly summarizes some points that can be of interest for anyone
modifying the FTS3 RESTful API.
5
6

**It is not intended for developers of client applications**. For them we have the
7
[auto generated API documentation](api.md), the list of [curl examples](api-curl.md) or the [easy bindings](easy/README.md).
8
9
10
11
12

Quick references
----------------
The service is written using [Pylons 0.9.7](https://pylons-webframework.readthedocs.org/en/v0.9.7/)

13
The database abstraction is done by [SQLAlchemy 0.8](http://docs.sqlalchemy.org/en/rel_0_8/)
14
15
16
17
18
19
20
21
22
23
24
25

There are a bunch of tests written using Python's [unittest](https://docs.python.org/2/library/unittest.html) module, and they can be executed
automatically with [nosetests](https://nose.readthedocs.org/en/latest/).

Branches
--------
### Main branches
#### develop
Integrated development version. Should be in a consistent state, but not necessarely stable.
This means, new features go here, and they should be in a workable state.

#### master
26
27
__Stable branch__. Only critical bugfixes. Runs on the FTS3 pilot service first, and then
in the FTS3 production services.
28
29

### Other branches
30
31
develop should be consistent and workable. For big changesets, you can keep them in a
separate branch, and merge them into develop when they are ready (remember to rebase first).
32
33
34
35
36
37
You don't need to keep these branches in the remote repositories.

Release cycle
-------------
1. New features are commited into develop. Big new features go into their own branch and later merged into develop.
    * Keep documentation up to date
38
2. When develop is ready for being a release candidate, merge develop into master.
39
    * Increase the version of develop after this!
40
3. When master is stable and ready for release
41
42
    1. Make sure the documentation is up to date
    2. Write release notes for the new version (contained in docs/releases)
43
    3. Tag, and mark version as released in JIRA (move any remaining tickets to the next release)
44
45
46

Guidelines
----------
47
48
This is just a small recopilatory of some guidelines that I consider worth considering when
working on this project.
49
50
51
52
53
54
55
They don't have to strictly be followed. Nevertheless, they are handy.

### A new source file is added
Remember to add the copyright notice

```
#   Copyright notice:
56
#   Copyright  CERN, 2017.
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.
```

### A wild bug appears!
If you find a bug, or someone reports one, it is helpful to write a regression test _before_ actually doing the fix.
So write the tests reproducing the buggy behavior, execute, and make sure they do fail.
Once the bug has a test that automatically reproduces it, you do the fix. Re-run the test, and now it should pass.

I would recommend to run the whole test suite afterwards, to make sure the fix didn't break anything else!
Precisely this is why I recommend writting a test. It will ensure this bug doesn't come back after some future modifications.

Remind creating a ticket in the JIRA tracker and linking it to the proper version!

### A new feature is added
Basically, the same idea applies. Write some tests for the new functionality, so you know you are achieving what you are expecting.

JIRA tickets are mandatory in this case. Otherwise, tracking release changes is hard.

### Logging
Python's [logging](https://docs.python.org/2/library/logging.html) is really handy and powerful. Use it!

P.S I recognise I don't use it as much as I should.

### Keep history clean and tidy
1. Write meaningful commit messages
2. Specify any relevant JIRA ticket in the commit
3. Avoid multipurpose jumbo commits
    * They should not contain unrelated changes (i.e. two bug fixes in one commit, bad)
4. Before pushing, group related commits (yes, [you can do this with git](http://stackoverflow.com/questions/6884022/collapsing-a-group-of-commits-into-one-on-git))
    * If you have two commits for one single bug fix, try grouping them whenever it makes sense.

Alejandro Alvarez Ayllon's avatar
Alejandro Alvarez Ayllon committed
99
100
101
102
103
104
Formatting
----------
Use [PEP8](https://www.python.org/dev/peps/pep-0008/). There are tools and IDE's that
check for consistency with this guidelines.
Do not kill yourself over it, but try to follow as much as possible.

105
106
107
108
109
110
111
112
113
114
115
116
FAQ
---

### Configuration files
* In a normally installed service, `/etc/fts3/fts3rest.ini`
* If you are running the tests with nosetests, then `src/fts3rest/test.ini` is used instead

### How do I run the tests
```bash
cd src/fts3rest/
nosetests -x
```
117
Note: In case the tests are run on Centos7, ./setup_pylons_plugin.py install --user needs to run first
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

That's it. For the tests, a SQLite database (/tmp/fts3.db) is used, so it is safe to run them as many times as you want.
The option `-x` lets nosetests know that it should stop running as soon as it encounters an error, so you can omit it.

If you have `nosestests1.1` installed, you can run the test suite as follows

```bash
cd src/fts3rest/
nosetests1.1 --with-coverage --cover-package=fts3rest
```

That will give coverage information. This is, which lines have been triggered by the tests.

### Can I see the queries that SQLAlchemy runs?
Yes, you can. Just edit the relevant configuration file, look for `[logger_sqlalchemy]` and set the level to INFO.
The queries will be dumped into the log file.