Thank you for considering a contribution!

The following contains a set of guides on how you can contribute to MATRX. These guides are unlikely to be complete, and may be subject to change. Feel free to offer suggestions or contributions to this document as well!

I have a question!

If you have a question, feel free to post it, or perhaps we already have your answer in the FAQ. We will do our best to reply as quick as possible. These questions can regard anything MATRX related, whether it is about usage, code or its vision.

If you do not wish to post your question, you can also e-mail it to info@matrx.com.

I am a user, how can I contribute?

You are a user of MATRX when you use the python package in your project. Since we cannot guarantee that MATRX fulfils every need, we can imagine you have ideas and suggestions on new features or improvements. Perhaps you even found a bug and wish the report it! We appreciate any suggestions or bug report you can throw at us, so feel free to do so.

I have a suggestion!

Great! We love suggestions.

You can provide us with suggestions by filing a request. This makes your suggestion accessible to everyone in the MATRX project and neatly fits in our workflow.

We do have some requests when you make an issue, whether it is a suggestion for a minor improvement or a completely new feature. These are as follows:

  • Give it a descriptive title. This helps us to quickly identify and filter on the suggestions.
  • Describe if it is related to a problem. If your suggestion is related to a problem you are facing, describe that problem for us. This helps us understand the motivation behind the suggestion.
  • Provide a detailed description. The more detail, the better.
  • Give us concrete examples. Examples allows us to know where to position the suggestion while adding even more detail.

The trick for us with suggestions and new features is to find out what you want to achieve. If we blindly add the suggestion without knowing the reasons behind it, it may not end up as intended. Hence, the more detail, the better. If we feel we lack sufficient detail, we will ask you for more.

It may occur that a suggestion is requested multiple times, in this case we will address this to you and ask if you agree with merging the issues for you.

If you find it cumbersome to make an issue, you can e-mail it to info@matrx.com

I found a bug!

Although we do our best, we cannot guarantee we squashed all bugs before a release. So if you found one for us, we will gladly help you with a work around to get you
back on track and fix it as soon as possible.

A bug is anything in MATRX that does not work as intended or causes harmful or annoying effects. If you feel you found a bug, you might save yourself some trouble with a cursory search through this list. If the bug is already present, feel free to comment on that bug report that you have to deal with the same thing.

If you cannot find your bug, feel free to file a bug report. Make sure you do the following:

  • Give it a descriptive title. This helps us to quickly identify and filter the bug reports.
  • Give it a concise description. So we can quickly grasp the issue.
  • Describe the exact steps that reproduce the problem. Please add as much detail as possible. We will have to replicate the bug by ourselves to be able to fix it. What would really help is a code snippet that causes it.
  • Describe what you expected to happen. This helps us understand your intentions, and whether there is another way to achieve what you want to achieve.
  • Add the stack trace. If available, please add the full stacktrace you received. This helps us to identify where the bug occurs.

If you do not feel at ease making a bug report in an issue, you can e-mail it to info@matrx.com.

I am a developer, how can I contribute?

Awesome! We always love to welcome new and aspiring MATRX developers. As a developer you can freely contribute to MATRX, and spend as much or as little time as you want. We do have a few style guides and a certain workflow, but you can read about that here.

I wish to take up an issue!

Great! This is a good start to make a first contribution. If you are new to MATRX development, we suggest you start with an Issue labeled as ‘Beginner’. Here you can find a list of them.

Please follow our Workflow when working on this issue. If you have any questions, feel free to add them in the issue you are working on and add the label ‘help wanted’ so we know you have questions or need help. You can even assign people to your issue if you wish to receive help from specific people.

I know how to fix a bug!

Nice, we love to hear that. If you see a bug report (see this list), and know how to solve it feel free to assign the bug to yourself and fix it. Perhaps you already came across the same bug and already implemented a solution locally. If so, feel free to point to the solution in the issue and integrate it into MATRX itself.

Do mind to follow our Workflow, otherwise things can become quite a mess.

I wish to review someone’s code!

To do so, assign yourself to the pull request or make a new one and switch to the appropriate branch. Do not forget to change the label of the Pull Request accordingly (see our Workflow).

The code review allows us to maintain MATRX’ quality, while also including the community in code development of others. Two see more than one. When you review the code, you can be as thorough as you want, but atleast focus on the following:

  • Does the code do or fix what the issue intended?
  • Does the code follow the styleguides?
  • Is the code fully documented?

When making or updating a pull request, be sure you follow the template we provided you (you see it when creating a new pull request). It should contain the following:

  • The related issue.
  • The description of the work that was done.
  • Who is responsible for the work.
  • Any release notes if applicable.

Style guides

In MATRX we have a few style guides we try to follow, we listed them below.

Git commit messages

Some quick pointers to make concise, readable and consistent commit messages:

  • Use the present tense (“Adds …” not “Added …”)
  • Limit the first line to 72 characters or less.
  • Reference Issues or Pull Request liberally after the first line.

Git Branch names

All branch names are brief, and do not contain spaces (use a dash instead).

Issue branches begin with their issue numbers, followed by the Issue title or a recognizable summary thereof. For example: “#46-Request-if-action-is-possible”.

Release branches always start with “Release-”, where is the next major or minor version number. For example: “release-1.2”

Hotfix branches always start with “Hotfix-”, where is the next hotfix version number. For example: “hotfix-1.2.12”

Python style guide

We strictly adhere to the original Python style guide, as defined by PEP-8. To make it easier to adhere to this style guide, please make use of a Linter.

Documentation style guide

We write our documentation in the NumpyDoc style. See here for an extensive guide.

Workflow

Below we describe the steps of our workflow. For more information, we follow the Git Branching model. We highly suggest you read through this explanation of it. Below we only give the steps of over flow, that post explains it in detail.

  1. As User: Create an Issue.
    1. Write the Issue according to the Contribution Guidelines.
    2. Assign appropriate labels to the Issue.
  2. As Developer: Work on an Issue.
    1. Assign the Issue to yourself or another.
    2. Create an Issue branch.
    3. Perform work, and commit regularly.
  3. As Developer: Create a Pull Request.
    1. Create a Pull Request for the Issue branch into dev according to the Contribution Guidelines.
    2. Wait or assign someone to the Pull Request.
    3. Respond to questions, remarks or requests from the reviewer.
  4. As Maintainer: Handle a Pull Request.
    1. Review the code according to the Contribution Guidelines.
    2. Provide feedback or remarks when needed, including potential required changes, to the Developer.
    3. If ready, perform the merge.
    4. Change the Issue labels if needed.
    5. Close the Issue.
    6. Remove the Issue branch.
  5. As Maintainer: Deploy the next version.
    1. When a new release is warranted, create a new Release branch from dev.
    2. Update the version in matrx/__version__.py
    3. Create a new Pull Request from the Release branch into the Master branch.
    4. Describe in the Pull Request all changes.
    5. Add all release notes from the relevant Pull Requests to the HISTORY.txt file.
    6. Assign a second Maintainer to review the Pull Request.
    7. After review, perform the merge from the Release branch into the Master branch.
    8. Tag that merge appropriately.
    9. Deploy the master branch to the PyPi server with python setup.py deploy (or test for the test PyPi server).
  6. As Developer: Create a Hotfix.
    1. Create a bug report if not already done so (note: a single Hotfix branch is allowed to solve several bug reports if needed).
    2. Add or change the labels.
    3. Create a Hotfix branch from Master.
    4. Perform the hotfix.
    5. Perform a Deployment (see 5), except this is done from the hotfix branch directly on the master branch.

Deploying a new version

If you are a maintainer of MATRX, you will no doubt at some point want to deploy a new MATRX version. Just follow these steps for any major and minor release (hotfixes go a bit differently, see below):

  1. Write a draft release.
    Follow the template as any other release. The name is the new version, and starts with a description summary of the changes followed by some headers listing the changes in detail. This includes new features, bug fixes, any deprecations, documentation updates and community updates.
    Important; do not yet set a tag just yet and make sure you save it as a draft, not yet publish it.
  2. Create a release branch.
    Create a new branch from the ‘dev’ branch and name it the version (“vx.x.0”) and checkout to this branch.

    git checkout dev
    git checkout -b <vx.x.0>

  3. Update the version number.
    Update the `__version__.py` file. Specifically only update the `__version__` attribute in that file with the new version. Commit and push this version update to the release branch.
  4. Create a pull request to master.
    Make a new Pull Request of the release branch into Master. Set its labels, assign to the release milestone if available and to a fellow maintainer for review. This review will not check the code, it will focus on checking the release draft and the updated version number.
  5. Perform the Pull Request to master.
    When reviewed and approved by a fellow maintainer, complete the pull request by merging the release branch into the master branch. The preference is to squash any commits using an interactive rebase, followed by a fast-forward. This keeps the branches clean.
  6. Create a version tag.
    Use git to tag the master branch with the version you are releasing (“vx.x.0”), and push it.

    git pull
    git tag <vx.x.0> -a
    git push –tags

  7. Set the tag on the draft release.
    Now go back to you release draft on github, and tag the current master branch version with the same tag you just made.
  8. Deploy package to test.
    Now you are ready to build and upload the package. To do so run:

    python setup.py test

    This will upload it first to the PyPi test servers and allows you to check if everything is in working order.

  9. Deploy package to PyPi
    If deployment to the PyPi test servers works, then run: 

    python setup.py deploy

    which uploads the build to the actual PyPi servers.

  10. Publish the release.
    Now publish the draft release you made in the first step.
  11. Contact the community.
    Last but most important; reach out to the community! Make sure everyone knows there is a new version of MATRX available. Preferably through contacting the mailing list with a brief summary of the changes and a link to the draft release. A release is a reason to celebrate with the community!

Additional information

Issue and Pull Request labels

LabelCategory Description
coreTopicWork related to the core functionality
APITopicWork related to the API
front-endTopicWork related to the front end
testsTopicWork related to our tests or test tasks
documentationTopicImprovements or additions to documentation
websiteTopicWork related to our website
featureTypeNew feature
bugTypeWork on something that isn’t working
help-wantedFeedbackExtra attention is needed
requestFeedbackA request for a new enhancement
questionFeedbackA question about anything
wont-fixFeedbackThis will not be worked on
work-in-progressPull RequestA pull request which is still being worked on
needs-reviewPull RequestA pull request that needs review
under-reviewPull RequestA pull request under review
needs-testingPull RequestA pull request in need for testing
requires-changesPull RequestA pull request which needs changes

Discussions and voting on features

Currently MATRX is still quite new, and the vision for it is still flued. This means that there are many new features possible, but there is not yet a fully detailed release
plan for the coming versions. As such, we maintain a democratic way of determining which features we will focus on.

We do so by setting the ‘Request’ label on a feature and discuss its advantages in the comments. Here we will make an inventory of which users and research projects would benefit from this new feature. If there are more than one, this feature is accepted as a potential new contribution. The more would benefit, the quicker we will implement it. If there is only one benefactor, or the feature is made by ourselves, we will vote on it. On the majority the feature is accepted as a potential new contribution. If the vote fails, the proposed feature is rejected and closed.