Skip to content

Latest commit

 

History

History
133 lines (105 loc) · 5.64 KB

developers.md

File metadata and controls

133 lines (105 loc) · 5.64 KB
Raw

Developer notes

This document briefly summarizes some points that can be of interest for anyone modifying the FTS3 RESTful API.

It is not intended for developers of client applications. For them we have the auto generated API documentation, the list of curl examples or the easy bindings.

Quick references

The service is written using Pylons 0.9.7

The database abstraction is done by SQLAlchemy 0.8

There are a bunch of tests written using Python's unittest module, and they can be executed automatically with nosetests.

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

Stable branch. Only critical bugfixes. Runs on the FTS3 pilot service first, and then in the FTS3 production services.

Other branches

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). 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
  2. When develop is ready for being a release candidate, merge develop into master.
    • Increase the version of develop after this!
  3. When master is stable and ready for release
    1. Make sure the documentation is up to date
    2. Write release notes for the new version (contained in docs/releases)
    3. Tag, and mark version as released in JIRA (move any remaining tickets to the next release)

Guidelines

This is just a small recopilatory of some guidelines that I consider worth considering when working on this project. 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:
#   Copyright  CERN, 2017.
#
#   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 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)
    • If you have two commits for one single bug fix, try grouping them whenever it makes sense.

Formatting

Use PEP8. 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.

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

cd src/fts3rest/
nosetests -x

Note: In case the tests are run on Centos7, ./setup_pylons_plugin.py install --user needs to run first

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

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.