Skip to content

Guidelines for developers

Jump to bottom
francisco-dlp edited this page Nov 27, 2013 · 1 revision

General style rules

The Style Guide for Python Code (http://www.python.org/dev/peps/pep-0008/) should always apply.

You can check your code with the http://pypi.python.org/pypi/pep8.

Docstrings

Python Docstring Conventions (http://www.python.org/dev/peps/pep-0257/ should always apply.

Example:

def myfunction():
    """This is the first line of the docstring.
    This is the second line of the docstring.
    This is the last line of the docstring.

    """

The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

It is recommended to insert a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.

Commit conventions

brief summary (max 80 chars)

KEYWORD_ONE: long description that specifies what has been done (functions, methods, imports, renaming, moving etc.)

KEYWORD_TWO: same as before

KEYWORDS are:

  • BUG-FIX: when fixing a bug
  • ENHANCE: when improving existing code
  • NEW: when adding new code or modules
  • DELETE: when deleting modules
  • MOVE: when modifying code or modules without changing what they to
  • MERGE: when merging branches
  • RELEASE: when releasing code

Making a release

At the moment we have no stable code, therefore there are only two possible development states for the code:

  • alpha (the normal state in the repository)
  • beta (a development release the we have published in the website)

The version variable in hyperspy Release.py should be:

  • The previous release version followed by "+dev" for alpha (in development) code e.g. 0.6+dev
  • The release version for an official release e.g. 0.2
  • The release version followed by b1, b2 etc for pre-releases that do not contain the full set of features planned for the final version e.g. 0.7b1
  • The release version followed by rc1, rc2 etc for for pre-releases that contain the full set of features planned for the final version e.g. 0.7rc1.

To make a release:

  • Create a new branch for the release git checkout -b 0.7b1
  • Replace "+dev" with the release version in hyperspy/Release.py
  • Update the CHANGES file in the project's root folder
  • Add the version tag to the repository e.g. git tag v0.7b1
  • Commit with the RELEASE keyword
  • Append "+dev" to the release version in hyperspy/Release.py
  • Commit
Clone this wiki locally