- Types of contributions we are looking for
- Using the issue tracker
- Bug reports
- Feature requests
- Ground rules
- Pull requests
Thank you for considering contributing to Quinoa. Please read the information below to help make your contribution easy and effective for everyone involved.
Following these guidelines helps to communicate that you respect the time of the developers managing this project. In return, they will reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
There are many ways to contribute, from writing tutorials and HOWTOs, adding examples, improving the documentation, submitting bug reports and feature requests to writing code which can be incorporated into Quinoa itself.
One way to contribute to Quinoa is to create your own tool. A tool is the largest unit of interacting components, such as Walker or Inciter. Creating a new tool provides the largest degree of freedom in what and how the tool should do, what its goals are, what equations it solves, the numerical methods of choice, etc.
The main benefit of creating a new tool in Quinoa is to be able to build something almost entirely new, yet still not having to start it from scratch. This can be done by relying on the existing software infrastructure, including
- The Charm++ runtime system and its ecosystem of libraries, allowing distributed-memory-parallel asynchronous programming and providing automatic load balancing, fault tolerance, and many others, to enable high performance for small as well as large problems,
- A CMake build system that easily incorporates third-party libraries and enables integration of Charm++-generated code as well as MPI libraries,
- Command-line, and input-file parsers whose grammars are written purely in C++, allowing custom and arbitrary grammar definitions, specific to each tool, to enable user-friendly configuration of problems,
- Distributed parallel file I/O, with partitioners, converters, and solution-adaptive refinement for tetrahedron meshes,
- Automated testing infrastructure, capable of testing serial, synchronous (e.g., MPI) parallel, and asynchronous (e.g., Charm++) parallel functions and executables, using multiple compilers, operating systems, libraries, container technology, and code quality analysis,
- Beautiful, professional, and no-nonsense documentation, featuring an expertly-designed, as-you-type search-engine, whose result looks great on any device, including math and figures.
In summary, if you want to start a new tool but do not want to start from scratch, yet still want the above features (for free), you could create a new tool in Quinoa. If you are interested, contact us so we can discuss the best way to go about it.
Please do NOT report security vulnerabilities in public issues! Instead, please disclose responsibly by letting the Quinoa team know upfront. We will assess the issue as soon as possible and will give you an estimate for when we have a fix and release available.
The issue tracker on GitHub is the preferred channel for bug reports, feature requests, and submitting pull requests, but please do not use the issue tracker for personal support requests — use our Chat or email list for those.
A bug is a problem that can be demonstrated and reproduced. Good bug reports are extremely helpful. Thanks in advance for taking the time to produce a useful bug report.
Guidelines for bug reports:
- Use the GitHub issue search — check if the issue has already been reported.
- Check if the issue has been fixed — try to reproduce it using the HEAD of the
- Try to see if the bug can be reproduced by any of the regression tests — see the build page on how to run them.
- Try to reproduce the bug in
Debugmode — this can be configured by setting
A good bug report shouldn't leave others needing to chase you down for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What OS experiences the problem? What would you expect to be the outcome? All these details will help us fix any potential bugs.
Short and descriptive example bug report title
A summary of the issue and the OS environment in which it occurs. If suitable, include the steps required to reproduce the bug:
- This is the first step.
- This is the second step.
- Further steps, etc.
Attach the full screen output of both the TPL-cmake as well as the Quinoa-cmake build configuration steps. See Two-stage build.
Attach the input file and, if relevant, the input mesh file. If the mesh is large, try to reproduce it with a smaller mesh. If you cannot, use our file transfer service to send us the larger mesh and address the file to email@example.com.
Attach the full screen output of the run reproducing the problem, including those of the Charm++ runtime system as well as the call and stack traces.
Include any other information you want to share that is relevant to the issue being reported. This might include the lines of code that you have identified as causing the bug, and potential solutions.
Some bugs may be non-deterministic and thus may only be triggered occasionally while some other times the code appears to run just fine, producing correct output. If this happens, don't panic! ;-) Such bugs are usually due to the fact that in Charm++ (and thus in Quinoa) execution is asynchronous by default and that the runtime system may (and likely will) schedule messages and tasks (and thus execution) in a non-deterministic fashion (while still adhering to correctness as specified by the programmer). However, if the programmer misses a single path of many possible paths of execution, that is incorrect, which may lead to data races and other bugs and thus may only appear randomly. (Which we do all the time — that's why we have an extensive test suite.)
Such non-deterministic bugs are a bit a harder to reproduce. Here are some techniques that have helped us in the past trigger such bugs sooner rather than later:
- If the bug is reproduced in
Releasemode, see if it can also be reproduced in
- Build the Charm++ runtime system using randomized message queues". This mode increases the chances of appearance of such non-deterministic errors.
Run the case (or subset of regression tests) you believe will trigger the problem in an infinite shell loop and at the same time load all CPUs of the machine with something else. For example, do
while ctest -j36 -R asynclogic -L migration --output-on-failure; do :; done | c++filt
While the above is running, in another terminal window do
make clean && make -sj36
The above will use 36 CPU cores and run all regression tests that contain the string
asynclogicin their name and also exercise object migration. If/when the problem happens, the test will produce a screen output with demangled traces using the
- You can also turn on Charm++'s quiescence detection feature by passing the
-qcommand line argument to any of the Quinoa executables, which help identify a specific subset of asynchronous-logic bugs.
Feature requests are welcome. Please use the github issue tracker.
Please take a moment and consider whether your idea fits within the scope, aims, and philosophy of the project and the particular tool. Please provide as much detail and context as possible. Also see the Roadmap.
Here are the basic rules that all of us follow — we expect all contributors to do the same.
We require all contributors to sign a contributor license agreement (CLA).
If you are an individual and you are sure you own the intellectual property, then you will need to sign the above individual CLA. If you work for a company that wants to allow you to contribute your work, then you will need to sign a corporate CLA. If you would like to sign the corporate CLA, please send us an email so we can send it to you. Once we receive the signed CLA, we will be able to accept your pull requests.
NOTE: Only original source code from you and other people that have signed the CLA can be accepted into the main repository.
IMPORTANT: By contributing code, you agree to license your work under Quinoa's license.
We roughly follow the development model described here. As a consequence, our
master (stable) branch can lag behind our
develop (bleeding edge) branch. In a nutshell, we always develop new code on feature branches, forking
develop, and issue pull requests against branch
develop. We only occasionally merge to
We routinely work with three compilers: clang, gnu, and intel — this helps catching more errors, increases portability, and helps decipher more complex error messages. Using multiple compilers are not required but recommended since our automated testing exercises all of these compilers, and it is more time-effective to catch errors and warnings earlier than later.
Additionally, by default we build Quinoa turning on most (if not all) compiler warnings. (Also, our continuous integration testing turns all warnings to errors.) There are some exceptions to this rule:
- some warnings are turned off globally (these are in
compiler-specific settings— a different list for each compiler, and
- we turn off some warnings locally, when headers of third-party libraries and Charm++-generated code are included — these are collected under
To ensure good code quality we do not deviate from these settings, and we ask all contributors to do the same.
While it is possible to clone, build the dependencies for, build, and work on only a single tool, doing so may run the risk of breaking some of the code that such a single-tool build does not use without noticing it locally. Thus, we recommend, at least before pushing to a GitHub branch (e.g., before a pull request, building and running the tests for the full Quinoa build. If something breaks, our continuous integration will most likely catch it because they test all the tools, thus testing the full build locally (before publishing your changes) reduces the chances of such problems and saves time.
For example, on a workstation with 36 CPUs, run the following in the build directory
# Using Charm++'s non-SMP mode: ./charmrun +p 36 Main/unittest -v -q && ctest -j 36 --output-on-failure -LE extreme # in SMP mode: ./charmrun +p 34 --bind-to none Main/unittest -v -q +ppn 17 && ctest -j 36 --output-on-failure -LE extreme
We usually exclude tests labeled as extreme (which also excludes insane tests), because these would take long time, but sometimes we run those too, because we are ... insane ;-).
See the section on building Charm++ in SMP mode on how to build Charm++ in non-SMP and SMP mode.
We don't really have coding guidelines. Please try not to diverge significantly from the style of the existing code. This includes file and function definition headers, comments, and API documentation. Also, please keep line lengths max 80 characters. See also our priorities for writing code.
Though we occasionally post comments on GitHub's feed discussing pull requests, we have had a better experience and thus prefer using reviewable.io's interface. It is also more featureful and posts the review comments back to GitHub's PR page (which are still searchable by GitHub later).
Good pull requests (PR) — patches, improvements, new features — are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
Please ask first before embarking on any significant PR (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that we might not want to merge in.
If you have never created a pull request on GitHub before, here is a great tutorial on how it works.
The basic steps for those who are not members of GitHub's QuinoaComputing organization are as follows.
Fork the project, clone your fork (so it is available locally to work on), and configure remotes:
# Clone your fork of the repo into the current directory git clone https://github.com/<your-username>/<repo-name> # Navigate to the newly cloned directory cd <repo-name> # Assign the original repo to a remote called "upstream" git remote add upstream https://github.com/quinoacomputing/<repo-name>
If you cloned/updated a while ago, get the latest changes from upstream:
git checkout develop git pull upstream develop
Create a new topic/feature branch (off the main project's
developbranch) to contain your feature, change, or fix:
git checkout -b <topic-branch-name>
- At this point, you are ready to make your changes or develop your feature! Feel free to ask for help — everyone is a beginner at first ;-). If a developer asks you to rebase your PR (or merge in
develop), they're saying that a lot of code has changed, and that you need to update your branch so it's easier to merge. Make sure to update, or add to the tests when appropriate. Patches and features will not be accepted without passing the existing tests. See also the section on how to run the tests.
- If you added or changed a feature, make sure to document it accordingly so doxygen can generate the correct documentation.
Push your topic branch up to your fork:
git push origin <topic-branch-name>
- Open a pull request with a clear title and description.
Clone the repo and create a branch, forking
git clone https://github.com/quinoacomputing/<repo-name> cd <repo-name> git checkout develop git checkout -b <topic-branch-name>
- Make sure to update, or add to the tests when appropriate. Patches and features will not be accepted without passing the existing tests. See also the section on how to run the tests.
Push your topic branch up to our repo
git push origin <topic-branch-name>
- Once a pull request is good to go, you can tidy up your commit messages using Git's interactive rebase.
- Open a pull request with a clear title and description.