We're excited about new contributors and want to make it easy for you to help improve this project. If you run into problems, please open a GitHub issue.
If you want to contribute a fix, or a minor change that doesn't change the API, go ahead and open a pull request; see details on pull requests below.
If you're interested in making a larger change, we recommend you to open an issue for discussion first. That way we can ensure that the change is within the scope of this project before you put a lot of effort into it.
We use GitHub issues to track public bugs and feature requests. Please ensure your description is clear and, if reporting a bug, include sufficient instructions to be able to reproduce the issue.
Our commitment is to review new items promptly, within 3-5 business days as a general goal. Of course, this may vary with factors such as individual workloads, complexity of the issue or pull request, etc. Issues that have been reviewed will have a "triaged" label applied by the reviewer if they are to be kept open.
If you feel that an issue or pull request may have fallen through the cracks, tag an admin in a comment to bring it to our attention. (You can start with @RookieRick, and/or look up who else has recently merged PRs).
Flask-Rebar is developed both internally within Autodesk and via open-source contributions. To coordinate and avoid duplication of effort, we use two mechanisms:
- We use the "triaged" label to mark issues as having been reviewed. Unless there are outstanding questions that need to be ironed out, you can assume that if an issue is marked as "triaged," we have generated an internal ticket, meaning someone will eventually address it. Timing of this will largely depend on whether there's a driving need within our own codebases that relies on Flask-Rebar.
- Because internal ticketing is a black-box to our open source contributors, we will also make use of the "assignee" feature. If someone has picked up an internal ticket, there will be an assignee on the issue. If you see an open issue that doesn't have an assignee and that you would like to tackle please tag a maintainer in a comment requesting assignment, and/or open an early "WIP" pull request so we'll know the issue is already being worked, and can coordinate development efforts as needed.
Flask-rebar is built to work with Flask and Marshmallow. We also seek to play nice with major "extensions" related to those core technologies by including optional features. Examples include marshmallow-objects and marshmallow-enum. If you are adding functionality that relies on any extensions meant to augment core versions of Flask or Marshmallow, there are three things that you as a developer are responsible for before submitting a Pull Request: 1. Ensure that you are NOT introducing any code changes that would make an extension a requirement. An end-user must be able to pip install flask-rebar and use all basic features without requiring any additional libraries. 2. Ensure that your extra requirements are broken out as a separate item within extras_require in setup.py. 3. Update the pip install instructions below to add your newly included "extras."
We recommend using a virtual environment for development. Once within a virtual environment install the flask_rebar package:
pip install .[dev,enum]For zsh shell users, use
pip install '.[dev,enum]'We use black to format code and keep it all consistent within the repo. With that in mind, you'll also want to install the precommit hooks because your build will fail if your code isn't black:
pre-commit installTo run the test suite with the current version of Python/virtual environment, use pytest:
pytestFlask-Rebar supports multiple versions of Python, Flask, and Marshmallow and uses Travis CI to run the test suite with different combinations of dependency versions. These tests are required before a PR is merged.
- Fork the repo and create your branch from
master. - If you've added code that should be tested, add tests.
- If you've changed APIs, update the documentation.
- Make sure you commit message matches something like (chg|fix|new): COMMIT_MSG so gitchangelog can correctly generate the entry for your commit.
Links to notes from team meetings:
:doc:`meeting_notes/roadmap_2020Jan29`
We use GitHub Actions to automate releasing package versions to PyPI.
Warning
These steps must be completed by an administrator. We generally do at least patch releases fairly frequently, but if you have a feature that urgently requires release, feel free to reach out and request one and we'll do our best to accommodate.
Flask-Rebar uses semantic versions. Once you know the appropriate version part to bump, use the bumpversion tool which will bump the package version, add a commit, and tag the commit appropriately. Note, it's not a bad idea to do a manual inspection and any cleanup you deem necessary after running gitchangelog to ensure it looks good before then committing a "@cosmetic" update.
Note
Before completing the following steps, you will need to temporarily change settings on GitHub under branch protection rules to NOT include administrators. This is required to allow you to push the changelog update.
git checkout master
git pull # just to play it safe and make sure you're up to date
bumpversion patch # or major or minor if applicable
gitchangelog
# STOP HERE: inspect CHANGELOG.rst and clean up as needed before continuing
git commit -a -m "@cosmetic - changelog"Then push the new commits and tags:
git push && git push --tagsFinally, while you're waiting for GitHub to pick up the tagged version, build it, and deploy it to PyPi, don't forget to reset branch protection settings (for normal operation, administrators should be subject to these restrictions to enforce PR code review requirements).