Contributing to MMSP: The Mesoscale Microstructure Simulation Project
Thank you for spending some time with MMSP. We sincerely appreciate your interest, and hope you will consider contributing to the documentation, source code, and community at large. This code is open-source, and we really appreciate input from the community. There are several ways you can contribute, including editing or adding documentation, writing tutorials, submitting bug reports, requesting new features, and writing code to incorporate. If you'd like to help out, please do!
If you're looking for support or guidance, please visit our Gitter chat to talk with the developers and community members, or send an e-mail to trevor.keller@gmail.com.
- Help us to maintain a considerate and supportive community by reading and enforcing the Code of Conduct. Be nice to newcomers.
- Promote clean code by ensuring your code and documentation build with neither
warnings nor errors using compiler flags equivalent to GCC's
-Wall -pedantic
. - Engage with the community by creating issues for changes or enhancements you'd like to make. Discuss ideas the open and get feedback.
- Maximize reusability by keeping code simple. Program in C if possible, and generally follow the Google C++ Style Guide. Avoid creating new classes if possible.
- Document new functions and classes with Doxygen-compatible comments in the source code.
Interested in helping, but unsure where to start? Consider proofreading the PDF documentation and reporting or fixing errors! There's bound to be a typo in there. Or look through the existing issues for fixes or enhancements you're interested in. The number of comments on an issue can indicate its level of difficulty, as well as the impact closing it will have.
If you're brand new to open source, welcome! You might benefit from the GitHub Help Pages and a tutorial.
MMSP uses git version control with a branching workflow,
summarized below. Following this workflow ensures a pristine master
branch
that remains synchronized, and allows collaborators to quickly and easily review
contributions for content and quality.
The core mantra is never commit to master
. On mesoscale/mmsp,
master
is the rolling release branch, and code must only be merged into it
following continuous integration testing, code review, and discussion.
Changes are made on branches, using master
as the trunk. Ideally, a branch
is created based on an issue, which captures a feature or hotfix
to MMSP. To paraphrase illustrations of more involved workflows, a simple
branching model for MMSP looks like the following, with B
indicating a branch
named ___
, M
a commit with message "___"
, ?
a pull request, and D
deletion of a branch. Note that branches are numbered sequentially, using the
number of the issue outlining the missing or broken functionality to
be patched.
mesoscale/ origin/ origin/
master hotfix feature hotfix feature
:
|
+-----------------------------------------B issue4
| |
+--------------------------B bug5 M "create function"
| M "missing ;" M "update docs"
| ?----------------+ |
"merge bug5" M---------+ | |
| D D |
+-----------------------------------------M "merge master"
| ?-----------------------+
| | M "address comments"
| M-----------------------+
"merge issue4" M-----------------+ |
| D D
:
Please neither commit directly to the master
branch, nor push directly to
mesoscale/mmsp.
- Create a fork of MMSP on your personal GitHub account.
- For obvious changes, such as typos or edits to
.gitignore
, you can edit your fork directly in the browser, then file a pull request. - Most changes begin with an Issue. If one does not exist, create it.
- On your local machine, use the command line to work on your local fork of
MMSP. Create a working branch off of
master
. If you're working, for example, on issue #42, function template documentation:- Fork mesoscale/mmsp and clone it to your local machine.
Your fork is a
git remote
with the aliasorigin
by default. git pull https://github.com/mesoscale/mmsp.git master
to update your localmaster
branch from the main repository.git checkout -b issue42_function-template-documentation master
to create a local feature branch off ofmaster
.- Write your edits, updates, or feature code.
git status
,git add -u
,git status
, andgit commit
, in that order, to add your changes. If something is amiss, follow the terminal guidance to fix it.- Write a concise commit message (first line), then in-depth commentary below using the keywords "Addresses" or "Closes" where appropriate.
git push origin issue42_summarize-usage-in-pseudocode
to push the working branch to your fork on GitHub.
- Fork mesoscale/mmsp and clone it to your local machine.
Your fork is a
- Visit GitHub and make the pull request official. Please fill out the pull
request template and assign a reviewer &emdash;
@tkphd
if noone else suits.
Obvious fixes will be merged quickly. Enhancements may undergo a code review, which we typically conduct using reviewable.