From 7aee5059431372b74472889409d9f2cc2ab8856c Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Mon, 16 Mar 2015 23:53:42 +0100 Subject: [PATCH 1/7] docs: Add development environment guide Fixes #994 --- docs/devenv.rst | 593 ++++++++++++++++++++++++++++++++++++ docs/devtools.rst | 43 --- docs/index.rst | 1 + docs/installation/index.rst | 5 +- 4 files changed, 597 insertions(+), 45 deletions(-) create mode 100644 docs/devenv.rst diff --git a/docs/devenv.rst b/docs/devenv.rst new file mode 100644 index 00000000..48a7bc30 --- /dev/null +++ b/docs/devenv.rst @@ -0,0 +1,593 @@ +.. _devenv: + +*********************** +Development environment +*********************** + +This page describes a common development setup for working with Mopidy and +Mopidy extensions. Of course, there may be other ways that work better for you +and the tools you use, but here's one recommended way to do it. + +.. contents:: + :local: + + +Initial setup +============= + +The following steps help you get a good initial setup. They build on each other +to some degree, so if you're not very familiar with Python development it might +be wise to proceed in the order laid out here. + +.. contents:: + :local: + + +Install Mopidy the regular way +------------------------------ + +Install Mopidy the regular way. Mopidy has some non-Python dependencies which +may be tricky to install. Thus we recommend to always start with a full regular +Mopidy install, as described in :ref:`installation`. That is, if you're running +e.g. Debian, start with installing Mopidy from Debian packages. + + +Make a development workspace +---------------------------- + +Make a directory to be used as a workspace for all your Mopidy development:: + + mkdir ~/mopidy-dev + +It will contain all the Git repositories you'll check out when working on +Mopidy and extensions. + + +Make a virtualenv +----------------- + +Make a Python `virtualenv `_ for Mopidy +development. The virtualenv will wall of Mopidy and its dependencies from the +rest of your system. All development and installation of Python dependencies +versions of Mopidy and extensions are done inside the virtualenv. This way your +regular Mopidy install, which you set up in the first step, is unaffected by +your hacking and will always be working. + +Most of us use the `virtualenvwrapper +`_ to ease working with +virtualenvs, so that's what we'll be using for the examples here. First, +install and setup virtualenvwrapper as described in their docs. + +To create a virtualenv named ``mopidy`` which use Python 2.7, allows access to +system-wide packages like GStreamer, and use the Mopidy workspace directory as +the "project path", run:: + + mkvirtualenv -a ~/mopidy-dev --python `which python2.7` \ + --system-site-packages mopidy + +Now, each time you open a terminal and want to activate the ``mopidy`` +virtualenv, run:: + + workon mopidy + +This will both activate the ``mopidy`` virtualenv, and change the current +working directory to ``~/mopidy-dev``. + + +Clone the repo from GitHub +-------------------------- + +Once inside the virtualenv, it's time to clone the ``mopidy/mopidy`` Git repo +from GitHub:: + + git clone https://github.com/mopidy/mopidy.git + +When you've cloned the ``mopidy`` Git repo, ``cd`` into it:: + + cd ~/mopidy-dev/mopidy/ + +With a fresh clone of the Git repo, you should start out on the ``develop`` +branch. This is where all features for the next feature release lands. To +confirm that you're on the right branch, run:: + + git branch + + +Install development tools +------------------------- + +We use a number of Python development tools. The :file:`dev-requirements.txt` +file has comments describing what we use each dependency for, so we might just +as well show include the file verbatim here: + +.. literalinclude:: ../dev-requirements.txt + +You probably won't use all of these development tools, but at least a +majority of them. Install them all into the active virtualenv by running `pip +`_:: + + pip install --upgrade -r dev-requirements.txt + +To upgrade the tools in the future, just rerun the exact same command. + + +Install Mopidy from the Git repo +-------------------------------- + +Next up, we'll want to run Mopidy from the Git repo. There's two reasons for +this: First of all, it lets you easily change the source code, restart Mopidy, +and see the change take effect. Second, it's a convenient way to keep at the +bleeding edge, testing the latest developments in Mopidy itself or test some +extension against the latest Mopidy changes. + +Assuming you're still inside the Git repo, use pip to install Mopidy from the +Git repo in an "editable" form:: + + pip install --editable . + +This will not copy the source code into the virtualenv's ``site-packages`` +directory, but instead create a link there pointing to the Git repo. Using +``cdsitepackages`` from virtualenvwrapper, we can quickly show that the +installed :file:`Mopidy.egg-link` file points back to the Git repo:: + + $ cdsitepackages + $ cat Mopidy.egg-link + /home/user/mopidy-dev/mopidy + .% + $ + +It will also create a ``mopidy`` executable inside the virtualenv that will +always run the latest code from the Git repo. Using another +virtualenvwrapper command, ``cdvirtualenv``, we can show that too:: + + $ cdvirtualenv + $ cat bin/mopidy + ... + +The executable should contain something like this, using :mod:`pkg_resources` +to look up Mopidy's "console script" entry point:: + + #!/home/user/virtualenvs/mopidy/bin/python2 + # EASY-INSTALL-ENTRY-SCRIPT: 'Mopidy==0.19.5','console_scripts','mopidy' + __requires__ = 'Mopidy==0.19.5' + import sys + from pkg_resources import load_entry_point + + if __name__ == '__main__': + sys.exit( + load_entry_point('Mopidy==0.19.5', 'console_scripts', 'mopidy')() + ) + +.. note:: + + It still works to run ``python mopidy`` directly on the + :file:`~/mopidy-dev/mopidy/mopidy/` Python package directory, but if + you don't run the ``pip install`` command above, the extensions bundled + with Mopidy will not be registered with :mod:`pkg_resources`, making Mopidy + quite useless. + +Third, the ``pip install`` command will register the bundled Mopidy +extensions so that Mopidy may find them through :mod:`pkg_resources`. The +result of this can be seen in the Git repo, in a new directory called +:file:`Mopidy.egg-info`, which is ignored by Git. The +:file:`Mopidy.egg-info/entry_points.txt` file is of special interest as it +shows both how the above executable and the bundled extensions are connected to +the Mopidy source code: + +.. code-block:: ini + + [console_scripts] + mopidy = mopidy.__main__:main + + [mopidy.ext] + http = mopidy.http:Extension + local = mopidy.local:Extension + mpd = mopidy.mpd:Extension + softwaremixer = mopidy.softwaremixer:Extension + stream = mopidy.stream:Extension + +.. warning:: + + It's not uncommon to clean up in the Git repo now and then, e.g. by running + ``git clean``. + + If you do this, then the :file:`Mopidy.egg-info` directory will be removed, + and :mod:`pkg_resources` will no longer know how to locate the "console + script" entry point or the bundled Mopidy extensions. + + The fix is simply to run the install command again:: + + pip install --editable . + +Finally, we can go back to the workspace, again using a virtualenvwrapper +tool:: + + cdproject + + +.. _running-from-git: + +Running Mopidy from Git +======================= + +As long as the virtualenv is activated, you can start Mopidy from any +directory. Simply run:: + + mopidy + +To stop it again, press :kbd:`Ctrl+C`. + +Every time you change code in Mopidy or an extension and want to see it +live, you must restart Mopidy. + +If you wan't to iterate quickly while developing, it may sound a bit tedious to +restart Mopidy for every minor change. Then it's useful to have tests to +exercise your code... + + +.. _running-tests: + +Running tests +============= + +Mopidy has quite good test coverage, and we would like all new code going into +Mopidy to come with tests. + +.. contents:: + :local: + + +Test it all +----------- + +You need to know at least one command; the one that runs all the tests:: + + tox + +This will run exactly the same tests as `Travis CI +`_ runs for all our branches and pull +requests. If this command turns green, you can be quite confident that your +pull request will get the green flag from Travis as well, which is a +requirement for it to be merged. + +As this is the ultimate test command, it's also the one taking the most time to +run; up to a minute, depending on your system. But, if you have patience, this +is all you need to know. Always run this command before pushing your changes to +GitHub. + +If you take a look at the tox config file, :file:`tox.ini`, you'll see that tox +runs tests in multiple environments, including a ``flake8`` environment that +lints the source code for issues and a ``docs`` environment that tests that the +documentation can be built. You can also limit tox to just test specific +environments using the ``-e`` option, e.g. to run just unit tests:: + + tox -e py27 + +To learn more, see the `tox documentation `_ . + + +Running unit tests +------------------ + +Under the hood, ``tox -e py27`` will use `pytest `_ as the +test runner. We can also use it directly to run all tests:: + + py.test + +py.test has lots of possibilities, so you'll have to dive into their docs and +plugins to get full benefit from it. To get you interested, here are some +examples. + +We can limit to just tests in a single directory to save time:: + + py.test tests/http/ + +With the help of the pytest-xdist plugin, we can run tests with four processes +in parallel, which usually cuts the test time in half or more:: + + py.test -n 4 + +Another useful feature from pytest-xdist, is the possiblity to stop on the +first test failure, watch the file system for changes, and then rerun the +tests. This makes for a very quick code-test cycle:: + + py.test -f # or --looponfail + +With the help of the pytest-cov plugin, we can get a report on what parts of +the given module, ``mopidy`` in this example, is covered by the test suite:: + + py.test --cov=mopidy --cov-report=term-missing + +.. note:: + + Up to date test coverage statistics can also be viewed online at + `coveralls.io `_. + +If we want to speed up the test suite, we can even get a list of the ten +slowest tests:: + + py.test --durations=10 + +By now, you should be convinced that running py.test directly during +development can be very useful. + + +Continuous integration +---------------------- + +Mopidy uses the free service `Travis CI `_ +for automatically running the test suite when code is pushed to GitHub. This +works both for the main Mopidy repo, but also for any forks. This way, any +contributions to Mopidy through GitHub will automatically be tested by Travis +CI, and the build status will be visible in the GitHub pull request interface, +making it easier to evaluate the quality of pull requests. + +For each success build, Travis submits code coverage data to `coveralls.io +`_. If you're out of work, coveralls might +help you find areas in the code which could need better test coverage. + +In addition, we run a Jenkins CI server at https://ci.mopidy.com/ that runs all +test on multiple platforms (Ubuntu, OS X, x86, arm) for every commit we push to +the ``develop`` branch in the main Mopidy repo on GitHub. Thus, new code isn't +tested by Jenkins before it is merged into the ``develop`` branch, which is a +bit late, but good enough to get broad testing before new code is released. + + +.. _code-linting: + +Style checking and linting +-------------------------- + +We're quite pedantic about :ref:`codestyle` and try hard to keep the Mopidy +code base a very clean and nice place to work in. + +Luckily, you can get very far by using the `flake8 +`_ linter to check your code for issues before +submitting a pull request. Mopidy passes all of flake8's checks, with only a +very few exceptions configured in :file:`setup.cfg`. You can either run the +``flake8`` tox environment, like Travis CI will do on your pull request:: + + tox -e flake8 + +Or you can run flake8 directly:: + + flake8 + +If successful, the command will not print anything at all. + +.. note:: + + In some rare cases it doesn't make sense to listen to flake8's warnings. In + those cases, ignore the check by appending ``# noqa: `` to + the source line that triggers the warning. The ``# noqa`` part will make + flake8 skip all checks on the line, while the warning code will help other + developers lookup what you are ignoring. + + +.. _writing-docs: + +Writing documentation +===================== + +To write documentation, we use `Sphinx `_. See their +site for lots of documentation on how to use Sphinx. + +.. note:: + + To generate a few graphs which are part of the documentation, you need some + additional dependencies. You can install them from APT with:: + + sudo apt-get install python-pygraphviz graphviz + +To build the documentation, go into the :file:`docs/` directory:: + + cd ~/mopidy-dev/mopidy/docs/ + +Then, to see all available build targets, run:: + + make + +To generate an HTML version of the documentation, run:: + + make html + +The generated HTML will be available at :file:`_build/html/index.html`. To open +it in a browser you can run either of the following commands, depending on your +OS:: + + xdg-open _build/html/index.html # Linux + open _build/html/index.html # OS X + +The documentation at https://docs.mopidy.com/ is hosted by `Read the Docs +`_, which automatically updates the documentation +when a change is pushed to the ``mopidy/mopidy`` repo at GitHub. + + +Working on extensions +===================== + +Much of the above also applies to Mopidy extensions, though they're often a bit +simpler. They don't have documentation sites and their test suites are either +small and fast, or sadly missing entirely. Most of them use tox and flake8, and +py.test can be used to run their test suites. + +.. contents:: + :local: + + +Installing extensions +--------------------- + +As always, the ``mopidy`` virtualenv should be active when working on +extensions:: + + workon mopidy + +Just like with non-development Mopidy installations, you can install extensions +using pip:: + + pip install Mopidy-Scrobbler + +Installing an extension from its Git repo works the same way as with Mopidy +itself. First, go to the Mopidy workspace:: + + cdproject # or cd ~/mopidy-dev/ + +Clone the desired Mopidy extension:: + + git clone https://github.com/mopidy/mopidy-spotify.git + +Change to the newly created extension directory:: + + cd mopidy-spotify/ + +Then, install the extension in "editable" mode, so that it can be imported from +anywhere inside the virtualenv and the extension is registered and discoverable +through :mod:`pkg_resources`:: + + pip install --editable . + +Every extension will have a ``README.rst`` file. It may contain information +about extra dependencies required, development process, etc. Extensions usually +have a changelog in the readme file. + + +Upgrading extensions +-------------------- + +Extensions often have a much quicker life cycle than Mopidy itself, often with +daily releases in periods of active development. To find outdated extensions in +your virtualenv, you can run:: + + pip search mopidy + +This will list all available Mopidy extensions and compare the installed +versions with the latest available ones. + +To upgrade an extension installed with pip, simply use pip:: + + pip install --upgrade Mopidy-Scrobbler + +To upgrade an extension installed from a Git repo, it's usually enough to pull +the new changes in:: + + cd ~/mopidy-dev/mopidy-spotify/ + git pull + +Of course, if you have local modifications, you'll need to stash these away on +a branch or similar first. + +Depending on the changes to the extension, it may be necessary to update the +metadata about the extension package by installing it in "editable" mode +again:: + + pip install --editable . + + +Contribution workflow +===================== + +Before you being, make sure you've read the :ref:`contributing` page and the +guidelines there. This section will focus more on the practical workflow. + +For the examples, we're making a change to Mopidy. Approximately the same +workflow should work for most Mopidy extensions too. + +.. contents:: + :local: + + +Setting up Git remotes +---------------------- + +Assuming we already have a local Git clone of the upstream Git repo in +:file:`~/mopidy-dev/mopidy/`, we can run ``git remote -v`` to list the +configured remotes of the repo:: + + $ git remote -v + origin https://github.com/mopidy/mopidy.git (fetch) + origin https://github.com/mopidy/mopidy.git (push) + +For clarity, we can rename the ``origin`` remote to ``upstream``:: + + $ git remote rename origin upstream + $ git remote -v + upstream https://github.com/mopidy/mopidy.git (fetch) + upstream https://github.com/mopidy/mopidy.git (push) + +If you haven't already, `fork the repository +`_ to your own GitHub account. + +Then, add the new fork as a remote to your local clone:: + + git remote add myuser git@github.com:myuser/mopidy.git + +The end result is that you have both the upstream repo and your own fork as +remotes:: + + $ git remote -v + myuser git@github.com:myuser/mopidy.git (fetch) + myuser git@github.com:myuser/mopidy.git (push) + upstream https://github.com/mopidy/mopidy.git (fetch) + upstream https://github.com/mopidy/mopidy.git (push) + + +Creating a branch +----------------- + +Fetch the latest data from all remotes without affecting your working +directory:: + + git remote update + +Now, we are ready to create and checkout a new branch off of the upstream +``develop`` branch for our work:: + + git checkout -b fix/666-crash-on-foo upstream/develop + +Do the work, while remembering to adhere to code style, test the changes, make +necessary updates to the documentation, and making small commits with good +commit messages. All as described in :ref:`contributing` and elsewhere in +the :ref:`devenv` guide. + + +Creating a pull request +----------------------- + +When everything is done and committed, push the branch to your fork on GitHub:: + + git push myuser fix/666-crash-on-foo + +Go to the repository on GitHub where you want the change merged, in this case +https://github.com/mopidy/mopidy, and `create a pull request +`_. + + +Updating a pull request +----------------------- + +When the pull request is created, `Travis CI +`__ will run all tests on it. If something +fails, you'll get notified by email. You might as well just fix the issues +right away, as we won't merge a pull request without a green Travis build. See +:ref:`running-tests` on how to run the same tests locally as Travis CI runs on +your pull request. + +When you've fixed the issues, you can update the pull request simply by pushing +more commits to the same branch in your fork:: + + git push myuser fix/666-crash-on-foo + +Likewise, when you get review comments from other developers on your pull +request, you're expected to create additional commits which addresses the +comments. Push them to your branch so that the pull request is updated. + +.. note:: + + Setup the remote as the default push target for your branch:: + + git branch --set-upstream-to myuser/fix/666-crash-on-foo + + Then you can push more commits without specifying the remote:: + + git push diff --git a/docs/devtools.rst b/docs/devtools.rst index 93798071..ec80c543 100644 --- a/docs/devtools.rst +++ b/docs/devtools.rst @@ -5,49 +5,6 @@ Development tools Here you'll find description of the development tools we use. -Continuous integration -====================== - -Mopidy uses the free service `Travis CI `_ -for automatically running the test suite when code is pushed to GitHub. This -works both for the main Mopidy repo, but also for any forks. This way, any -contributions to Mopidy through GitHub will automatically be tested by Travis -CI, and the build status will be visible in the GitHub pull request interface, -making it easier to evaluate the quality of pull requests. - -In addition, we run a Jenkins CI server at http://ci.mopidy.com/ that runs all -test on multiple platforms (Ubuntu, OS X, x86, arm) for every commit we push to -the ``develop`` branch in the main Mopidy repo on GitHub. Thus, new code isn't -tested by Jenkins before it is merged into the ``develop`` branch, which is a -bit late, but good enough to get broad testing before new code is released. - -In addition to running tests, the Jenkins CI server also gathers coverage -statistics and uses flake8 to check for errors and possible improvements in our -code. So, if you're out of work, the code coverage and flake8 data at the CI -server should give you a place to start. - - -Documentation writing -===================== - -To write documentation, we use `Sphinx `_. See their -site for lots of documentation on how to use Sphinx. To generate HTML from the -documentation files, you need some additional dependencies. - -You can install them through Debian/Ubuntu package management:: - - sudo apt-get install python-sphinx python-pygraphviz graphviz - -Then, to generate docs:: - - cd docs/ - make # For help on available targets - make html # To generate HTML docs - -The documentation at http://docs.mopidy.com/ is automatically updated when a -documentation update is pushed to ``mopidy/mopidy`` at GitHub. - - Creating releases ================= diff --git a/docs/index.rst b/docs/index.rst index 395e683e..bb16239c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -135,6 +135,7 @@ Development :maxdepth: 1 contributing + devenv devtools codestyle extensiondev diff --git a/docs/installation/index.rst b/docs/installation/index.rst index c8deae59..dba1fb3a 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -7,8 +7,9 @@ Installation There are several ways to install Mopidy. What way is best depends upon your OS and/or distribution. -If you want to contribute to the development of Mopidy, you should first read -the general installation instructions, then have a look at :ref:`run-from-git`. +If you want to contribute to the development of Mopidy, you should first follow +the instructions here to install a regular install of Mopidy, then continue +with reading :ref:`contributing` and :ref:`devenv`. .. toctree:: From e981caf5e9e067ba61cedb0b4a8c35e8e88f5909 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 17 Mar 2015 00:00:35 +0100 Subject: [PATCH 2/7] docs: New contribution guidelines Fixes #830 --- docs/contributing.rst | 198 +++++++++++++++++------------------------- 1 file changed, 79 insertions(+), 119 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index f30e16bd..64f8d74b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -4,44 +4,81 @@ Contributing ************ -If you are thinking about making Mopidy better, or you just want to hack on it, -that’s great. Here are some tips to get you started. +If you want to contribute to Mopidy, here are some tips to get you started. -Getting started -=============== +.. _asking-questions: -#. Make sure you have a `GitHub account `_. +Asking questions +================ -#. If a ticket does not already exist `submit a ticket - `_ for your issue. - Make sure to clearly describe the issue, and if it is a bug: include steps - to reproduce. +Please use one of these channels for requesting help with Mopidy and its +extensions: -#. Fork the repository on GitHub. +- Our discussion forum: `discuss.mopidy.com `_. + Just sign in and fire away. + +- Our IRC channel: ``#mopidy`` on `irc.freenode.net `_, + with public `searchable logs `_. Be + prepared to hang around for a while, as we're not always around to answer + straight away. + +Before asking for help, it might be worth your time to read the +:ref:`troubleshooting` page, both so you might find a solution to your problem +but also to be able to provide useful details when asking for help. -Making changes -============== +Helping users +============= -#. Clone your fork on GitHub to your computer. +If you want to contribute to Mopidy, a great place to start is by helping other +users on IRC and in the discussion forum. This is a contribution we value +highly. As more people help with user support, new users get faster and better +help. For your own benefit, you'll quickly learn what users find confusing, +difficult or lacking, giving you some ideas for where you may contribute +improvements, either to code or documentation. Lastly, this may also free up +time for other contributors to spend more time on fixing bugs or implementing +new features. -#. Consider making a Python `virtualenv `_ for - Mopidy development to wall of Mopidy and it's dependencies from the rest of - your system. If you do so, create the virtualenv with the - ``--system-site-packages`` flag so that Mopidy can use globally installed - dependencies like GStreamer. If you don't use a virtualenv, you may need to - run the following ``pip`` and ``python setup.py`` commands with ``sudo`` to - install stuff globally on your computer. -#. Install dependencies as described in the :ref:`installation` section. +.. _issue-guidelines: -#. Install additional development dependencies:: +Issue guidelines +================ - pip install -r dev-requirements.txt +#. If you need help, see :ref:`asking-questions` above. The GitHub issue + tracker is not a support forum. -#. Checkout a new branch (usually based on ``develop``) and name it accordingly - to what you intend to do. +#. If you are not sure if is what you're experiencing is a bug or not, post in + the `discussion forum `__ first to verify that + its a bug. + +#. If you are sure that you've found a bug or have a feature request, check if + there's already an issue in the `issue tracker + `_. If there is, see if there is + anything you can add to help reproduce or fix the issue. + +#. If there is no exising issue matching your bug or feature request, create a + `new issue `_. Please include + as much relevant information as possible. If its a bug, including how to + reproduce the bug and any relevant logs or error messages. + + +Pull request guidelines +======================= + +#. Before spending any time on making a pull request: + + - If its a bug, :ref:`file an issue `. + + - If its an enhancement, discuss it with other Mopidy developers first, + either in a GitHub issue, on the discussion forum, or on IRC. Making sure + your ideas and solutions are aligned with other contributors greatly + increase the odds of your pull request being quickly accepted. + +#. Create a new branch, based on the ``develop`` branch, for every feature or + bug fix. Keep branches small and on topic, as that makes them far easier to + review. We often use the following naming convention for branches: - Features get the prefix ``feature/`` @@ -49,105 +86,28 @@ Making changes - Improvements to the documentation get the prefix ``docs/`` +#. Follow the :ref:`code style `, especially make sure the + ``flake8`` linter does not complain about anything. Travis CI will check + that your pull request is "flake8 clean". See :ref:`code-linting`. -.. _run-from-git: +#. Include tests for any new feature or substantial bug fix. See + :ref:`running-tests`. -Running Mopidy from Git -======================= +#. Include documentation for any new feature. See :ref:`writing-docs`. -If you want to hack on Mopidy, you should run Mopidy directly from the Git -repo. +#. Feel free to include a changelog entry in your pull request. The changelog + is in :file:`docs/changelog.rst`. -#. Go to the Git repo root:: +#. Write good commit messages. Here's three blog posts on how to do it right: - cd mopidy/ + - `Writing Git commit messages + `_ -#. To get a ``mopidy`` executable and register all bundled extensions with - setuptools, run:: + - `A Note About Git Commit Messages + `_ - python setup.py develop + - `On commit messages + `_ - It still works to run ``python mopidy`` directly on the ``mopidy`` Python - package directory, but if you have never run ``python setup.py develop`` the - extensions bundled with Mopidy isn't registered with setuptools, so Mopidy - will start without any frontends or backends, making it quite useless. - -#. Now you can run the Mopidy command, and it will run using the code - in the Git repo:: - - mopidy - - If you do any changes to the code, you'll just need to restart ``mopidy`` - to see the changes take effect. - - -Testing -======= - -Mopidy has quite good test coverage, and we would like all new code going into -Mopidy to come with tests. - -#. To run all tests, go to the project directory and run:: - - py.test - - To run tests with test coverage statistics:: - - py.test --cov=mopidy --cov-report=term-missing - - Test coverage statistics can also be viewed online at - `coveralls.io `_. - -#. Always check the code for errors and style issues using flake8:: - - flake8 - - If successful, the command will not print anything at all. Ignore the rare - cases you need to ignore a check use `# noqa: ` so we can lookup what - you are ignoring. - -#. Finally, there is the ultimate but a bit slower command. To run both tests, - docs build, and flake8 linting, run:: - - tox - - This will run exactly the same tests as `Travis CI - `_ runs for all our branches and pull - requests. If this command turns green, you can be quite confident that your - pull request will get the green flag from Travis as well, which is a - requirement for it to be merged. - - -Submitting changes -================== - -- One branch per feature or fix. Keep branches small and on topic. - -- Follow the :ref:`code style `, especially make sure ``flake8`` - does not complain about anything. - -- Write good commit messages. Here's three blog posts on how to do it right: - - - `Writing Git commit messages - `_ - - - `A Note About Git Commit Messages - `_ - - - `On commit messages - `_ - -- Send a pull request to the ``develop`` branch. See the `GitHub pull request - docs `_ for help. - - -Additional resources -==================== - -- IRC channel: ``#mopidy`` at `irc.freenode.net `_ - -- `Issue tracker `_ - -- `Mailing List `_ - -- `GitHub documentation `_ +#. Send a pull request to the ``develop`` branch. See the `GitHub pull request + docs `_ for help. From b2b7b8708198a87d307266aa2a19f1cbe0757320 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 17 Mar 2015 01:01:15 +0100 Subject: [PATCH 3/7] docs: Make devtools a pure release procedure page --- docs/index.rst | 2 +- docs/{devtools.rst => releasing.rst} | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) rename docs/{devtools.rst => releasing.rst} (93%) diff --git a/docs/index.rst b/docs/index.rst index bb16239c..06af9dcd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -136,7 +136,7 @@ Development contributing devenv - devtools + releasing codestyle extensiondev diff --git a/docs/devtools.rst b/docs/releasing.rst similarity index 93% rename from docs/devtools.rst rename to docs/releasing.rst index ec80c543..8a12cf7d 100644 --- a/docs/devtools.rst +++ b/docs/releasing.rst @@ -1,8 +1,10 @@ -***************** -Development tools -***************** +****************** +Release procedures +****************** -Here you'll find description of the development tools we use. +Here we try to keep an up to date record of how Mopidy releases are made. This +documentation serves both as a checklist, to reduce the project's dependency on +key individuals, and as a stepping stone to more automation. Creating releases From c90f08d8ea66301d55a3e249a406b2c31daf4571 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 17 Mar 2015 01:13:25 +0100 Subject: [PATCH 4/7] docs: Show another level of the about section in the ToC --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 06af9dcd..e91c491c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -132,7 +132,7 @@ Development =========== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 contributing devenv From b6b872b9c2dde4049ef0d8c936b38329fd7361ce Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 17 Mar 2015 12:20:35 +0100 Subject: [PATCH 5/7] docs: Fix typos from review Co-Authored-By: Nick Steel --- docs/contributing.rst | 14 +++++++------- docs/devenv.rst | 42 +++++++++++++++++++++--------------------- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 64f8d74b..1b3b1330 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -49,9 +49,9 @@ Issue guidelines #. If you need help, see :ref:`asking-questions` above. The GitHub issue tracker is not a support forum. -#. If you are not sure if is what you're experiencing is a bug or not, post in - the `discussion forum `__ first to verify that - its a bug. +#. If you are not sure if what you're experiencing is a bug or not, post in the + `discussion forum `__ first to verify that it's + a bug. #. If you are sure that you've found a bug or have a feature request, check if there's already an issue in the `issue tracker @@ -60,7 +60,7 @@ Issue guidelines #. If there is no exising issue matching your bug or feature request, create a `new issue `_. Please include - as much relevant information as possible. If its a bug, including how to + as much relevant information as possible. If it's a bug, including how to reproduce the bug and any relevant logs or error messages. @@ -69,12 +69,12 @@ Pull request guidelines #. Before spending any time on making a pull request: - - If its a bug, :ref:`file an issue `. + - If it's a bug, :ref:`file an issue `. - - If its an enhancement, discuss it with other Mopidy developers first, + - If it's an enhancement, discuss it with other Mopidy developers first, either in a GitHub issue, on the discussion forum, or on IRC. Making sure your ideas and solutions are aligned with other contributors greatly - increase the odds of your pull request being quickly accepted. + increases the odds of your pull request being quickly accepted. #. Create a new branch, based on the ``develop`` branch, for every feature or bug fix. Keep branches small and on topic, as that makes them far easier to diff --git a/docs/devenv.rst b/docs/devenv.rst index 48a7bc30..c67426f7 100644 --- a/docs/devenv.rst +++ b/docs/devenv.rst @@ -47,19 +47,19 @@ Make a virtualenv ----------------- Make a Python `virtualenv `_ for Mopidy -development. The virtualenv will wall of Mopidy and its dependencies from the -rest of your system. All development and installation of Python dependencies -versions of Mopidy and extensions are done inside the virtualenv. This way your -regular Mopidy install, which you set up in the first step, is unaffected by -your hacking and will always be working. +development. The virtualenv will wall off Mopidy and its dependencies from the +rest of your system. All development and installation of Python dependencies, +versions of Mopidy, and extensions are done inside the virtualenv. This way +your regular Mopidy install, which you set up in the first step, is unaffected +by your hacking and will always be working. Most of us use the `virtualenvwrapper `_ to ease working with virtualenvs, so that's what we'll be using for the examples here. First, install and setup virtualenvwrapper as described in their docs. -To create a virtualenv named ``mopidy`` which use Python 2.7, allows access to -system-wide packages like GStreamer, and use the Mopidy workspace directory as +To create a virtualenv named ``mopidy`` which uses Python 2.7, allows access to +system-wide packages like GStreamer, and uses the Mopidy workspace directory as the "project path", run:: mkvirtualenv -a ~/mopidy-dev --python `which python2.7` \ @@ -87,7 +87,7 @@ When you've cloned the ``mopidy`` Git repo, ``cd`` into it:: cd ~/mopidy-dev/mopidy/ With a fresh clone of the Git repo, you should start out on the ``develop`` -branch. This is where all features for the next feature release lands. To +branch. This is where all features for the next feature release land. To confirm that you're on the right branch, run:: git branch @@ -98,12 +98,11 @@ Install development tools We use a number of Python development tools. The :file:`dev-requirements.txt` file has comments describing what we use each dependency for, so we might just -as well show include the file verbatim here: +as well include the file verbatim here: .. literalinclude:: ../dev-requirements.txt -You probably won't use all of these development tools, but at least a -majority of them. Install them all into the active virtualenv by running `pip +Install them all into the active virtualenv by running `pip `_:: pip install --upgrade -r dev-requirements.txt @@ -115,7 +114,7 @@ Install Mopidy from the Git repo -------------------------------- Next up, we'll want to run Mopidy from the Git repo. There's two reasons for -this: First of all, it lets you easily change the source code, restart Mopidy, +this: first of all, it lets you easily change the source code, restart Mopidy, and see the change take effect. Second, it's a convenient way to keep at the bleeding edge, testing the latest developments in Mopidy itself or test some extension against the latest Mopidy changes. @@ -220,7 +219,7 @@ To stop it again, press :kbd:`Ctrl+C`. Every time you change code in Mopidy or an extension and want to see it live, you must restart Mopidy. -If you wan't to iterate quickly while developing, it may sound a bit tedious to +If you want to iterate quickly while developing, it may sound a bit tedious to restart Mopidy for every minor change. Then it's useful to have tests to exercise your code... @@ -282,8 +281,8 @@ We can limit to just tests in a single directory to save time:: py.test tests/http/ -With the help of the pytest-xdist plugin, we can run tests with four processes -in parallel, which usually cuts the test time in half or more:: +With the help of the pytest-xdist plugin, we can run tests with four Python +processes in parallel, which usually cuts the test time in half or more:: py.test -n 4 @@ -294,7 +293,7 @@ tests. This makes for a very quick code-test cycle:: py.test -f # or --looponfail With the help of the pytest-cov plugin, we can get a report on what parts of -the given module, ``mopidy`` in this example, is covered by the test suite:: +the given module, ``mopidy`` in this example, are covered by the test suite:: py.test --cov=mopidy --cov-report=term-missing @@ -322,15 +321,16 @@ contributions to Mopidy through GitHub will automatically be tested by Travis CI, and the build status will be visible in the GitHub pull request interface, making it easier to evaluate the quality of pull requests. -For each success build, Travis submits code coverage data to `coveralls.io +For each successful build, Travis submits code coverage data to `coveralls.io `_. If you're out of work, coveralls might help you find areas in the code which could need better test coverage. In addition, we run a Jenkins CI server at https://ci.mopidy.com/ that runs all -test on multiple platforms (Ubuntu, OS X, x86, arm) for every commit we push to -the ``develop`` branch in the main Mopidy repo on GitHub. Thus, new code isn't -tested by Jenkins before it is merged into the ``develop`` branch, which is a -bit late, but good enough to get broad testing before new code is released. +tests on multiple platforms (Ubuntu, OS X, x86, arm) for every commit we push +to the ``develop`` branch in the main Mopidy repo on GitHub. Thus, new code +isn't tested by Jenkins before it is merged into the ``develop`` branch, which +is a bit late, but good enough to get broad testing before new code is +released. .. _code-linting: From 8a0bf3c25f2a07f012443337c3793a099306c742 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 17 Mar 2015 13:16:39 +0100 Subject: [PATCH 6/7] docs: Include commit message tips in the guidelines --- docs/contributing.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 1b3b1330..ecfaea90 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -98,7 +98,19 @@ Pull request guidelines #. Feel free to include a changelog entry in your pull request. The changelog is in :file:`docs/changelog.rst`. -#. Write good commit messages. Here's three blog posts on how to do it right: +#. Write good commit messages. + + - Follow the template "topic: description" for the first line of the commit + message, e.g. "mpd: Switch list command to using list_distinct". See the + commit history for inspiration. + + - Use the rest of the commit message to explain anything you feel isn't + obvious. It's better to have the details here than in the pull request + description, since the commit message will live forever. + + - Write in the imperative, present tense: "add" not "added". + + For more inspiration, read these blog posts: - `Writing Git commit messages `_ From bdee9478893936e4e51b12d2258ec6f585f8aa23 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 17 Mar 2015 21:24:32 +0100 Subject: [PATCH 7/7] docs: Fix review comments --- docs/conf.py | 2 +- docs/contributing.rst | 17 ++++++++++------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 88ea49f0..22ecb6fa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -84,7 +84,7 @@ def setup(app): # -- General configuration ---------------------------------------------------- -needs_sphinx = '1.0' +needs_sphinx = '1.3' extensions = [ 'sphinx.ext.autodoc', diff --git a/docs/contributing.rst b/docs/contributing.rst index ecfaea90..b5230b18 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -12,13 +12,14 @@ If you want to contribute to Mopidy, here are some tips to get you started. Asking questions ================ -Please use one of these channels for requesting help with Mopidy and its -extensions: +Please get in touch with us in one of these ways when requesting help with +Mopidy and its extensions: - Our discussion forum: `discuss.mopidy.com `_. Just sign in and fire away. -- Our IRC channel: ``#mopidy`` on `irc.freenode.net `_, +- Our IRC channel: `#mopidy `_ + on `irc.freenode.net `_, with public `searchable logs `_. Be prepared to hang around for a while, as we're not always around to answer straight away. @@ -80,11 +81,13 @@ Pull request guidelines bug fix. Keep branches small and on topic, as that makes them far easier to review. We often use the following naming convention for branches: - - Features get the prefix ``feature/`` + - Features get the prefix ``feature/``, e.g. + ``feature/track-last-modified-as-ms``. - - Bug fixes get the prefix ``fix/`` + - Bug fixes get the prefix ``fix/``, e.g. ``fix/902-consume-track-on-next``. - - Improvements to the documentation get the prefix ``docs/`` + - Improvements to the documentation get the prefix ``docs/``, e.g. + ``docs/add-ext-mopidy-spotify-tunigo``. #. Follow the :ref:`code style `, especially make sure the ``flake8`` linter does not complain about anything. Travis CI will check @@ -110,7 +113,7 @@ Pull request guidelines - Write in the imperative, present tense: "add" not "added". - For more inspiration, read these blog posts: + For more inspiration, feel free to read these blog posts: - `Writing Git commit messages `_