Welcome to the xonsh developer's guide! This is a place for developers to place information that does not belong in the user's guide or the library reference but is useful or necessary for the next people that come along to develop xonsh.
Note
All code changes must go through the pull request review procedure.
xonsh is a pure Python project, and so we use PEP8 (with some additions) to ensure consistency throughout the code base.
It is important to refer to things and concepts by their most specific name. When writing xonsh code or documentation please use technical terms appropriately. The following rules help provide needed clarity.
- User-facing APIs should be as generic and robust as possible.
- Tests belong in the top-level
testsdirectory. - Documentation belongs in the top-level
docsdirectory.
- Code must have associated tests and adequate documentation.
- User-interaction code (such as the Shell class) is hard to test. Mechanism to test such constructs should be developed over time.
- Have extreme empathy for your users.
- Be selfish. Since you will be writing tests you will be your first user.
xonsh uses PEP8 for all Python code. The following rules apply where PEP8 is open to interpretation.
- Use absolute imports (
import xonsh.tools) rather than explicit relative imports (import .tools). Implicit relative imports (import tools) are never allowed. - Use
'single quotes'for string literals, and"""triple double quotes"""for docstrings. Double quotes are allowed to prevent single quote escaping, e.g."Y'all c'mon o'er here!" - We use sphinx with the numpydoc extension to autogenerate API documentation. Follow the numpydoc standard for docstrings described here.
- Simple functions should have simple docstrings.
- Lines should be at most 80 characters long. The 72 and 79 character recommendations from PEP8 are not required here.
- All Python code should be compliant with Python 3.4+. At some unforeseen date in the future, Python 2.7 support may be supported.
- Tests should be written with nose using a procedural style. Do not use unittest directly or write tests in an object-oriented style.
- Test generators make more dots and the dots must flow!
First, install nose: http://nose.readthedocs.org/en/latest/
To perform all unit tests:
$ cd tests/
$ nosetestsThis will recursively look through the currently directory, open up every file named test* and run every function (or method) named test*.
Nosetests can also take file(s) as an argument. For example, to run just the lexer and parser module tests:
$ nosetests test_lexer.py test_parser.pyHappy testing!
Documentation takes many forms. This will guide you through the steps of successful documentation.
No matter what language you are writing in, you should always have documentation strings along with you code. This is so important that it is part of the style guide. When writing in Python, your docstrings should be in reStructured Text using the numpydoc format.
The docstrings that you have written will automatically be connected to the website, once the appropriate hooks have been setup. At this stage, all documentation lives within xonsh's top-level docs directory. We uses the sphinx tool to manage and generate the documentation, which you can learn about from the sphinx website. If you want to generate the documentation, first xonsh itself must be installed and then you may run the following command from the docs dir:
~/xonsh/docs $ make htmlFor each new module, you will have to supply the appropriate hooks. This should be done the first time that the module appears in a pull request. From here, call the new module mymod. The following explains how to add hooks.
Python documentation lives in the docs/api directory. First, create a file in this directory that represents the new module called mymod.rst. The docs/api directory matches the structure of the xonsh/ directory. So if your module is in a sub-package, you'll need to go into the sub-package's directory before creating mymod.rst. The contents of this file should be as follows:
mymod.rst:
.. _xonsh_mymod:
=======================================
My Awesome Module -- :mod:`xonsh.mymod`
=======================================
.. currentmodule:: xonsh.mymod
.. automodule:: xonsh.mymod
:members:This will discover all of the docstrings in mymod and create the appropriate webpage. Now, you need to hook this page up to the rest of the website.
Go into the index.rst file in docs/xonsh or other subdirectory and add mymod to the appropriate toctree (which stands for table-of-contents tree). Note that every sub-package has its own index.rst file.
Building the website/documentation requires the following dependencies:
The xonsh website source files are located in the docs directory. A developer first makes necessary changes, then rebuilds the website locally by executing the command:
$ make htmlThis will generate html files for the website in the _build/html/ folder. The developer may view the local changes by opening these files with their favorite browser, e.g.:
$ google-chrome _build/html/index.htmlOnce the developer is satisfied with the changes, the changes should be committed and pull-requested per usual. Once the pull request is accepted, the developer can push their local changes directly to the website by:
$ make push-rootMainline xonsh development occurs on the master branch. Other branches may be used for feature development (topical branches) or to represent past and upcoming releases.
All releases should have a release candidate ('-rc1') that comes out 2 - 5 days prior to the scheduled release. During this time, no changes should occur to a special release branch ('vX.X.X-release').
The release branch is there so that development can continue on the develop branch while the release candidates (rc) are out and under review. This is because otherwise any new developments would have to wait until post-release to be merged into develop to prevent them from accidentally getting released early.
As such, the 'vX.X.X-release' branch should only exist while there are release candidates out. They are akin to a temporary second level of staging, and so everything that is in this branch should also be part of master.
Every time a new release candidate comes out the vX.X.X-release should be tagged with the name 'X.X.X-rcX'. There should be a 2 - 5 day period of time in between release candidates. When the full and final release happens, the 'vX.X.X-release' branch is merged into master and then deleted.
If you have a new fix that needs to be in the next release candidate, you should make a topical branch and then pull request it into the release branch. After this has been accepted, the topical branch should be merged with master as well.
The release branch must be quiet and untouched for 2 - 5 days prior to the full release.
The release candidate procedure here only applies to major and minor releases. Micro releases may be pushed and released directly without having a release candidate.
When releasing xonsh, make sure to do the following items in order:
- Review ALL issues in the issue tracker, reassigning or closing them as needed.
- Ensure that all issues in this release's milestone have been closed. Moving issues to the next release's milestone is a perfectly valid strategy for completing this milestone.
- Perform maintenance tasks for this project, see below.
- Write and commit the release notes.
- Review the current state of documentation and make appropriate updates.
- Bump the version (in code, documentation, etc.) and commit the change.
- If this is a release candidate, tag the release branch with a name that matches that of the release:
- If this is the first release candidate, create a release branch called 'vX.X.X-release' off of develop. Tag this branch with the name 'X.X.X-rc1'.
- If this is the second or later release candidate, tag the release branch with the name 'X.X.X-rcX'.
- If this is the full and final release (and not a release candidate), merge the release branch into the master branch. Next, tag the master branch with the name 'X.X.X'. Finally, delete the release branch.
- Push the tags upstream
- Update release information on the website.
None currently.
To perform the release, run these commands for the following tasks:
pip upload:
$ ./setup.py sdist uploadconda upload:
$ rm -f /path/to/conda/conda-bld/src_cache/xonsh.tar.gz
$ conda build --no-test recipe
$ conda convert -p all -o /path/to/conda/conda-bld /path/to/conda/conda-bld/linux-64/xonsh-X.X.X-0.tar.bz2
$ binstar upload /path/to/conda/conda-bld/*/xonsh-X.X.X*.tar.bz2website:
$ cd docs
$ make clean html push-rootPortions of this page have been forked from the PyNE documentation, Copyright 2011-2015, the PyNE Development Team. All rights reserved.