First of all thank you for contributing to Broadway! 🎉
There are many ways in which you can contribute. Broadway has a lot of sister open source projects which need maintenance too.
If you find issues in any of these, please feel free to make Issues or Pull Requests. Reporting issues itself is contributing!
Please make issues as detailed as possible. Include error messages, logs and output in code blocks. If you are making feature requests please explain in detail what purpose the feature would serve. Please keep in mind that Broadway should not contain course-specific features or code. Broadway's design has been kept generic for all courses to use and provide the flexibility to use it. Consider building services around Broadway if you want course specific changes.
Please keep PRs as small as possible so its easier for reviewers to review it and get back to you. If you have a lot of changes, try splitting them up into smaller parts and stacking PRs. It makes a world of a difference for reviewers. It will also be easier spot potential errors.
Please keep meaningful commit messages, branch names and description. Summarize your changes in the description. Link all the issues
your PR is attemption to fix. Possibly prepend the issues links with "Resolves " so that the issue is immediately close when the PR
is merged to master.
Please squash and merge so that the commit history on master looks cleaner and easier to navigate.
Please run/modify the tests each time a change is made to the logic or structure. Make sure you have a local mongod instance running or else all tests will fail. You can run the tests using:
pytest -v tests/api --doctest-modulesfollowed by our integration tests with:
docker-compose -f docker-compose.test.yml up --build --force-recreate --exit-code-from testsIn addition, we run a linter/formatter to keep things standard and clean. For formatting, be sure to execute black
black broadway/ tests/and then flake8
flake8 --config=setup.cfgbefore opening a pull request.
Please be cautious of adding blocking calls in the application logic because Tornado uses a single-threaded event loop. Therefore, one blocking call will prevent the API from serving requests and hence tamper with the entire distributed system. For instance, it might prevent the API from listening to heartbeats and as a result the server will consider worker nodes to be dead.
If you want to use blocking calls, please make them asynchronous. Asynchronous and non-blocking IO guide for Tornado
Almost all maintainers of this project are full-time students. We tend to get busy with college schedule and studies of our own. Please be patient while we review your contributions. We would definitely get back to you because we want to improve Broadway as much as you do!