Skip to content
This repository has been archived by the owner on Mar 16, 2023. It is now read-only.

Contributing to MineMeld

Jump to bottom
Luigi Mori edited this page Jun 17, 2016 · 7 revisions

Want to hack on MineMeld? Awesome! We have a developer's guide that explains setting up a MineMeld development environment.

This page contains information about reporting issues as well as some tips and guidelines useful to experienced open source contributors. Finally, make sure you read our community guidelines before you start participating.

Topics

Reporting security issues

The MineMeld maintainers take security seriously. If you discover a security issue, please bring it to their attention right away!

Please DO NOT file a public issue, instead send your report privately to [email protected].

Security reports are greatly appreciated and we will publicly thank you for it.

Reporting other issues

A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate a well-written, thorough bug report, and will thank you for it!

File the issue under the most appropriate repository:

Please check that the selected issue database doesn't already include that problem or suggestion before submitting an issue. If you find a match, you can use the "subscribe" button to get notified on updates. Do not leave random "+1" or "I have this too" comments, as they only clutter the discussion, and don't help resolving it. However, if you have ways to reproduce the issue or have additional information that may help resolving the issue, please leave a comment.

Also include the steps required to reproduce the problem if possible and applicable. This information will help us review and fix your issue faster. When sending lengthy log-files, consider posting them as a gist (https://gist.github.com). Don't forget to remove sensitive data from your logfiles before posting (you can replace those parts with "REDACTED").

Quick contribution tips and guidelines

This section gives the experienced contributor some tips and guidelines.

Pull requests are always welcome

Not sure if that typo is worth a pull request? Found a bug and know how to fix it? Do it! We will appreciate it. Any significant improvement should be documented as a GitHub issue before anybody starts working on it.

We are always thrilled to receive pull requests. We do our best to process them quickly. If your pull request is not accepted on the first try, don't get discouraged!

Design and cleanup proposals

You can propose new designs for existing MineMeld features. You can also design entirely new features. We really appreciate contributors who want to refactor or otherwise cleanup our project.

Document your proposal with a GitHub issue in the appropriate repository. Please prefix the issue with Proposal: for new design or new features, and with Cleanup: for cleanup proposals.

Branches

We follow a simplified version of the popular git flow.

  • master MUST always be production-deployable.
  • develop may not be ready for production but should pass all existing tests.

The only branches that will be merged directly into master are develop (for a release) or hotfixes for significant bugs that need immediate attention. Hotfixes will merge into master and develop. All other development forks off from the develop branch and merges back into it.

Conventions

Fork the repository and make changes on your fork in a feature branch:

  • If it's a bug fix branch, name it XXXX-something where XXXX is the number of the issue.
  • If it's a feature branch, create an enhancement issue to announce your intentions, and name it XXXX-something where XXXX is the number of the issue.

Update the documentation when creating or modifying features. Test your documentation changes for clarity, concision, and correctness, as well as a clean documentation build.

Write clean code. Check the coding style guide for details.

Pull request descriptions should be as clear as possible and include a reference to all the issues that they address.

Commit messages must start with a capitalized and short summary (max. 50 chars) written in the imperative, followed by an optional, more detailed explanatory text which is separated from the summary by an empty line.

Code review comments may be added to your pull request. Discuss, then make the suggested modifications and push additional commits to your feature branch. Post a comment after pushing. New commits show up in the pull request automatically, but the reviewers are notified only when you comment.

Pull requests must be cleanly rebased on top of ``develop` without multiple branches mixed into the PR.

Git tip: If your PR no longer merges cleanly, use rebase develop in your feature branch to update your pull request rather than merge develop.

Include an issue reference like Closes #XXXX or Fixes #XXXX in commits that close an issue. Including references automatically closes the issue on a merge.

Please do add yourself to the AUTHORS file.

Please see the Coding Style for further guidelines.

Merge approval

MineMeld maintainers use :shipit: in comments on the code review to indicate acceptance.

Sign your work

The sign-off is a simple line at the end of the explanation for the patch. Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below (from developercertificate.org):

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Then you just add a line to every git commit message:

Signed-off-by: Joe Smith <[email protected]>

Use your real name (sorry, no pseudonyms or anonymous contributions.)

If you set your user.name and user.email git configs, you can sign your commit automatically with git commit -s.

MineMeld community guidelines

We want to create a vibrant community around MineMeld where people feel proud and happy to contribute to. To help with this we've adopted the Contributor Covenant Code of Conduct.

Coding Style

Python code should be compliant with Kenneth Reitz's Code Style, that is PEP8 with some concessions on line lengths.

Credits

We based these on the excellent Docker and Combine contribution guidelines.

Clone this wiki locally