Skip to content

Latest commit

 

History

History
141 lines (84 loc) · 6.05 KB

CONTRIBUTING.md

File metadata and controls

141 lines (84 loc) · 6.05 KB
Raw

Questions about Medusa?

To get your questions answered, please ask on the #pymedusa IRC channel on irc.freenode.net

Contributing to Medusa

  1. Getting Involved
  2. How To Report Bugs
  3. Tips For Submitting Code

Getting Involved

There are a number of ways to get involved with the development of Medusa. Even if you've never contributed code to an Open Source project before, we're always looking for help identifying bugs, cleaning up code, writing documentation and testing.

The goal of this guide is to provide the best way to contribute to the official Medusa repository. Please read through the full guide detailing How to Report Bugs.

Discussion

If you think you've found a bug please file it in the bug tracker.

Most of the Medusa development team can be found in the #pymedusa IRC channel on irc.freenode.net.

How to Report Bugs

Make sure it is a Medusa bug

Many bugs reported are actually issues with the user mis-understanding of how something works (there are a bit of moving parts to an ideal setup) and most of the time can be fixed by just changing some settings to fit the users needs.

If you are new to Medusa, it is usually a much better idea to ask for help first in the Medusa IRC channel. You will get much quicker support, and you will help avoid tying up the Medusa team with invalid bug reports.

Try the latest version of Medusa

Bugs in old versions of Medusa may have already been fixed. In order to avoid reporting known issues, make sure you are always testing against the latest build/source. Also, we put new code in the develop branch first before pushing down to the master branch (which is what the binary builds are built off of).

Reporting the issue

If the above steps fail and you are sure its a bug, issues are tracked in the Medusa issue tracker.

Tips For Submitting Code

Code

ALWAYS follow Medusa Coding Standards

Review regularly as they are subject to change and submissions will not be accepted until they meet our guidelines.

NEVER write your patches to the master branch - it gets messy (I say this from experience!)

ALWAYS USE A "TOPIC" BRANCH!

Personally I like the branch-feature_name format that way its easy to identify the branch and feature at a glance. Also please make note of any issue number in the pull commit so we know what you are solving (it helps with cleaning up the related items later).

Reporting

Please follow these guidelines before reporting a bug:

  1. Update to the latest version — Check if you can reproduce the issue with the latest version from the develop branch.

  2. Use the search on Medusa issues — check if the issue has already been reported. If it has been, please comment on the existing issue.

  3. Provide a means to reproduce the problem — Please provide as much details as possible, e.g. Medusa log files (obfuscate apikey/passwords), browser and operating system versions, how you started Medusa, and of course the steps to reproduce the problem.

Pull requests

Pull requests are welcome and the preferred way of accepting code contributions.

Please follow these guidelines before sending a pull request:

  1. Update your fork to the latest upstream version.

  2. Use the develop branch to base your code off of. Create a topic-branch for your work. We will not merge your 'dev' branch, or your 'master' branch, only topic branches, coming from dev are merged.

  3. Follow the coding conventions of the original repository. Do not change line endings of the existing file, as this will rewrite the file and loses history.

  4. Keep your commits as autonomous as possible, i.e. create a new commit for every single bug fix or feature added.

  5. Always add meaningful commit messages. We should not have to guess at what your code is supposed to do.

  6. One pull request per feature. If you want multiple features, send multiple PR's

Please follow this process; it's the best way to get your work included in the project:

  • Fork the project, clone your fork, and configure the remotes:
   # clone your fork of the repo into the current directory in terminal
   git clone [email protected]:<your username>/Medusa.git
   # navigate to the newly cloned directory
   cd Medusa
   # assign the original repo to a remote called "upstream"
   git remote add upstream https://github.com/pymedusa/Medusa.git

  • If you cloned a while ago, get the latest changes from upstream:

    # fetch upstream changes
git fetch upstream
# make sure you are on your 'master' branch
git checkout master
# merge upstream changes
git merge upstream/master

  • Make sure that your develop branch is up to date:

    # Switch to the develop branch
git checkout develop
# Pull down any updates
git pull

  • Create a new topic branch to contain your feature, change, or fix:

    git checkout -b <topic-branch-name> develop

  • Commit your changes in logical chunks. or your pull request is unlikely be merged into the main project. Use git's interactive rebase feature to tidy up your commits before making them public.

  • Push your topic branch up to your fork:

    git push origin <topic-branch-name>

  • Open a Pull Request with a clear title and description.

Code guidelines

Read and follow the Medusa Coding Standards. Review these regularly as they are subject to change and code will not be accepted if it does not adhere to the standards.