You are reading the documentation for version 3.0 of ProMod3.
You may also want to read the documentation for:
1.3
2.0
2.1
3.1
3.2
ProMod3 Setup¶The following should give an overview of how this project is set up. Anyone planning to develop parts of ProMod3 should read this! Important topics are Git branches, the directory structure and tightly linked with this also CMake. Git Branches¶Basically we have two, sometimes three major branches.
Release branches, usually labelled The
The reason to be a bit restrictive on branches which end up in actual releases, should be mostly obvious: ProMod3 is used by productive services as a third party toolbox. There it is not an item of active development and people probably have no insight in its internals. So messing up a new release creates a lot of extra work for a lot of people. First for the developer of a service to find out that ProMod3 has turned malicious, then for the maintainer of this package to figure out that its your contribution messing things up and in the end for you, fixing the problems. The place where you may get messy is your own Git branch within the ProMod3
repository. This is basically where you should develop your project. Once you
created something that could go into a release, tidy things up according to the
rules from above and merge it into To set up your own branch, start from a current $ git checkout develop # switch to branch develop
$ git pull --rebase # update branch develop
$ git checkout -b <BRANCHNAME> # create branch <BRANCHNAME> and switch to it
Over time, $ git commit -m '<DESCRIPTION>' # commit changes including a comment
Hiding your changes away from Git just for updating files is a bit more involved. Everything is easily stored on an internal stack and needs to be fetched from there, once the branch was updated. One major problem in the past was a possible loss of code by those operations. If the update changes a file you have changed, too, and stashed away, this may end up in a non-resolvable merge conflict and your changes are lost. Usually the log tells you, which files were recently modified. Moving all current changes to the stack is achieved by: $ git stash save
To revive them, use: $ git stash pop
After cleaning up your branch, switch to $ git checkout develop
$ git pull --rebase
$ git checkout <BRANCHNAME>
Now for actually updating your branch, there are two different ways: merging
and rebasing. A rebase may only be done, if you never pushed your branch to
the origin of the repository (otherwise you will mess up history, in the worst
case $ git rebase develop
For branches which are available to others, do a proper merge: $ git merge develop
This may require some manual conflict solving and will end up in a merge commit. Git Hooks¶Git hooks are scripts invoked by Git in connection to certain commands. ProMod3 currently provides one for commit. It is installed by $ cp extras/pre_commit/pre-commit .git/hooks/
Its task is applying coding standards and doing a bunch of other checks on the
files involved in a commit. Everything around the script is hosted in
$ python .git/hooks/pre-commit
If you ever have to skip the hook, $ git commit --no-verify
does the trick. But checks are always run on the complete file containing changes, not only on the lines changed. This means if you opt out of an issue, it will reappear next time that very file changes. For checking Python code, the pre-commit hook employs Pylint, to make sure
we stay close to PEP 8. If you feel the need to make changes to the Pylint
call, please make sure you fully understand what the complaints are. Sometimes
PEP 8 sounds overly restrictive but it may help with performance and
compatibility with Python 3. For ProMod3 it is also important that the code
looks similar throughout the various modules. So do not disable a check because
it just seems inconvenient or you do not understand why Pylint is croaking at
what looks like ‘working’ code. But then there are also cases where Pylint is
not smart enough to cope with valid PEP 8 code. For changes with valid cause,
the configuration flushed into Pylint may be found at
Directory Structure¶The directory structure of the ProMod3 repository is supposed to ‘keep everything together that belongs together’. That is, code, documentation and extra data should be gathered on a per-module basis immediately in the repository root. The directory structure of your module should look like this: promod3.git/ Project folder
your_module/ Module directory
CMakeLists.txt CMake configuration
data/ Extra data (if needed)
CMakeLists.txt CMake configuration
...
doc/ Documentation
CMakeLists.txt CMake configuration
your_module.rst Overview/frame of your module
...
pymod/ Python code
CMakeLists.txt CMake configuration
__init__.py Init file needed for import
submodule1.py Code
...
src/ C/ C++ code
CMakeLists.txt CMake configuration
source1.cc C++ code
source2.hh Header
...
tests/ Unit tests
CMakeLists.txt CMake configuration
data/ Test data (if needed)
...
test_your_module.py Unit tests for your_module
test_submodule1.py Unit tests for submodule1
...
Additionally to the module directories there are a few extra folders:
CMake¶The attentive reader may have noticed all the The
|
ContentsSearchEnter search terms or a module, class or function name. Previous topicNext topicYou are here
|