-
Notifications
You must be signed in to change notification settings - Fork 766
Contributing
To contribute code, there needs to be an issue in the issue tracker first. The issue can be for a bug or a new feature, but should be self-contained and for "one thing" only.
The workflow then should be as follows.
- This workflow is intended to allow to do work in self-contained, atomic chunks that are easy to review, test and merge - and easy to follow in the history of the main repository.
- Git can be hard. Here is a good Git book online and free.
Fork the repository via the GitHub Web user interface, clone your fork and add the main repository as upstream (needs only be done once):
git clone git@github.com:oberstet/AutobahnPython.git
cd AutobahnPython/
git remote add upstream git@github.com:tavendo/AutobahnPython.git
Work on the issue then happens on a feature/bug branch. For an issue #123, the branch must be named issue212. Create a branch for the issue in your local repository:
git checkout -b issue212
Now work on the issue. When you are done, make the final commit with a commit message that contains "fixes #212" (this will allow automatically linking stuff):
git add .
git commit -m "fixes #212"
Then rebase your changes to master (which might have gotten other commits in the meantime) and push to your (forked) repository on GitHub:
git checkout master
git fetch --all
git merge upstream/master
git checkout issue212
git rebase master
git push origin issue212
Now go to your issue branch in the GitHub Web user interface
https://github.com/oberstet/AutobahnPython/tree/issue212
and press "Compare & pull request". Review your changes and then issue a "Pull Request".
Someone with write access to the main repository will then need to merge the PR into the main repo.
FIXME: We want "clean history". That means: not only rebasing to master, but we don't want to have all the intermediary commits a developer had accumulate on an issue branch. See here for what that means.
Releases are tagged in the repository like v0.8.9 and published on PyPi.
The documentation is generated using Sphinx from Python docstrings and hand-created pages (written in RST). The target format is (static) HTML pages which are then hosted on
Docs root folder is here and the entry page is index.rst.
There is a README here that describes how to generate docs.
For end-to-end testing of any WebSocket related code, we use Autobahn|Testsuite.
For end-to-end testing of WAMP related code, we should use the testsuite as well, but this depends on fixing this.
Unit tests can be found in the test directories of the respective submodules.
For example, this folder contains tests for the (generic) parts of WAMP.
We use Twisted Trial, which is an extension of the Python standard unittest framework.
The reason we use Trial is that it has specific machinery for testing asynchronous code. The downside is that we can't test Python 3 and/or asyncio using this (due to the Twisted dependency).
To run all unit tests, change to the package root directory (the one containing setup.py) and run
trial autobahn
You can also run specific tests only
trial autobahn.wamp.test