-
Notifications
You must be signed in to change notification settings - Fork 771
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 [email protected]:oberstet/AutobahnPython.git
cd AutobahnPython/
git remote add upstream [email protected]: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"
Before pushing to your (remote) fork on GitHub, rebase your changes to master and squash any insignificant (intermediary) commits:
git checkout master
git fetch --all
git merge upstream/master
git checkout issue212
git rebase -i master
git push origin issue212
"rebasing" and "squashing" are two best practices in Git based workflows for achieving a easy to follow and clean history.
E.g. the master branch might have gotten other commits in the meantime, and without rebasing, but a simple merge of master, the commits of your issue branch would end up interleaved with those on master. Very hard to follow.
Also, we want "clean history". That means: not only rebasing to master, but we don't want to have intermediary (insignificant) commits a developer had accumulate on an issue branch each appear as it's own commit. Like "oops, type in last commit, fix that" and stuff like this. It is perfectly fine for an issue branch to consist of multiple commits in the end, but each commit should be meaningful.
In the Git world, that runs under the term "squashing". See here for what that means.
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.
Releases are tagged in the repository like v0.8.9 and published on PyPi.
Only developers with write access to the main repository can tag a release and upload to 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