Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. Note further, that we follow and would like to emphasize the following additional examples of unacceptable behavior:
When contributing to this project, please note the following style conventions that are enforced (partially strictly enforced by the CI server).
Most importantly, reflect your changes in the Changelog so we do not have to reconstruct it from the GIT history.
When you have contributed code to M-M.E.S.S. you and the content of your contribution will be mentioned in the project’s contributors file. Contributions are grouped by release, so if you have contributed code to multiple releases, you will be mentioned for each of these releases.
If, for some reason, you do not wish to be mentioned in the contributors file, please give us a short note. Also note that we cannot give attributions to trivial changes, such as fixing a typo in the documentation or correcting a very simple bug. However, your changes including your authorship will always be included in the git history of the project.
In general we prefer descriptive identifiers that support easier reading and understanding of the code. Other than that, follow the guidelines below:
Naming of functions:
mess_
operatormanager
function inside the usfs
folderprivate
folder.Code Style:
checkcode
tests in MATLAB, i.e. you are not allowed to have red or orange marks in the MATLAB editor. However, when absolutely necessary those warnings may be suppressed. (E.g. in ADI the growth of the solution factor is avoidable only with significant implementation overhead)not()
rather than ~
for negation for easier reading. (Enforced by CI!)eqn
, opts
, and oper
as mandatory input and output arguments. For example mess_lradi
is a core Lyapunov solver that is intended for maximum abstraction and needs these arguments, while mess_lyap
is intended as a large-scale replacement for MATLAB’s lyap
and thus intended for matrices.usfs
system and access to eqn.A_
or eqn.E_
is prohibited. (see help mess_usfs
for details on the usfs
system and philosophy)opts
should contain a separate substructure for each algorithm/solver-function and options are only allowed on the top level when they are absolutely necessary for consistent operation. For example mess_lrnm
and mess_lradi
have their options in opts.nm
and opts.adi
. On the other hand, opts.LDL_T
or opts.norm
used to decide global settings like the shape of the factorization computed, or the norm that should consistently be used for measuring progress are allowed on the top level.% comment
rather than %comment
.y = a * x + b;
and not y=a*x+b;
Our GIT repository provides maximum flexibility for forking, branching, merging, and commenting on work done. For the sake of maintainability follow these guidelines:
We use an extensive test system on our continuous integration (CI) server to ensure that new features do not break old functionality and all features work in both MATLAB and GNU Octave, both with and without toolboxes/packages installed. Currently CI time is limited to 2 hours and all tests should be finished in that time.
We distinguish between so called unit tests and system tests. Here, unit tests are testing the smallest possible building blocks. As a rule of thumb, a routine that does not call external functions, or only private functions is a candidate for a unit test.
Larger routines that run a hierarchy of other stuff, such as our demonstrator functions in the DEMOS
folder should be used to perform the much bigger system tests.
DEMOS
should be accompanied by a system test calling them on an, ideally, small example. (See comment about the CI time above)usfs
sets should be checked by unit tests. Use non-symmetric systems and system matrices where possible!