Skip to content

Latest commit

 

History

History
175 lines (107 loc) · 4.99 KB

CONTRIBUTING.md

File metadata and controls

175 lines (107 loc) · 4.99 KB
Raw

Contributing

Contributions are welcome, and they are greatly appreciated!. You can contribute code, documentation, tests, bug reports. Every little bit helps, and credit will always be given. If you plan to make a contribution it would be great if you first announce that on the issue tracker.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/textX/Arpeggio/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.

Write Documentation

Arpeggio could always use more documentation, whether as part of the official Arpeggio docs, in docstrings, or even on the web in blog posts, articles, and such.

How to Test the Documentation Locally

Arpeggio is currently using mkdocs, a documentation generator, to generate the docs into html files.

To test the docs locally, you need to follow the first 3 instructions at the Get Started! section

  1. Fork the repo (one-time effort)
  2. Clone your fork locally (one-time effort)
  3. Create a virtualenv for the fork and install the relevant libraries (one-time effort)

Once you complete the above 3 instructions, you can now:

  1. Activate the virtualenv
  2. Run mkdocs serve at the root folder

mkdocs will run a webserver that serves the documentation at 127.0.0.1:8000

To make changes to the configurations, you can look at mkdocs.yml. For more information on how to use mkdocs, visit this site.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/textX/Arpeggio/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here's how to set up Arpeggio for local development.

  1. Fork the Arpeggio repo on GitHub.

  2. Clone your fork locally:

     $ git clone [email protected]:your_name_here/Arpeggio.git

  3. Install your local copy into a virtualenv. This is how you set up your fork for local development:

     $ cd Arpeggio/
 $ python -m venv venv
 $ source venv/bin/activate
 $ ./install-dev.sh

    Previous stuff is needed only the first time. To continue working on Arpeggio later you just do:

     $ cd Arpeggio/ 
 $ source venv/bin/activate

    Note that on Windows sourcing syntax is a bit different. Check the docs for virtualenv.

    An excellent overview of available tools for Python environments management can be found here

    To verify that everything is setup properly run tests:

     $ flake8
 $ py.test tests/functional/

  4. Create a branch for local development::

     $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you're done making changes, check that your changes pass flake8, the tests, and have a look at the coverage:

     $ flake8
 $ py.test tests/functional/
 $ coverage run --source textx -m py.test tests/functional
 $ coverage report

    You can run all this at once with provided script runtests.sh

     $ ./runtests.sh

    In case you have doubts, have also a look at the html rendered version of the coverage results:

     $ coverage html

  6. Commit your changes and push your branch to GitHub:

     $ git add .
 $ git commit -m "Your detailed description of your changes."
 $ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds/changes functionality, the docs should be updated.
  3. The pull request should work for supported Python versions. Check https://github.com/textX/Arpeggio/actions and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ py.test tests/functional/mytest.py

or a single test:

$ py.test tests/functional/mytest.py::some_test

Credit

This guide is based on the guide generated by Cookiecutter and cookiecutter-pypackage project template.