MOTOR-1224 Convert top level docs to Markdown (#244)
* MOTOR-1224 Convert top level docs to Markdown * add md files * fix manifest * address review
This commit is contained in:
Steven Silvester
GitHub
parent
9a86b616dd
commit
3f8314db62
68
CONTRIBUTING.md
Normal file
68
CONTRIBUTING.md
Normal file
@ -0,0 +1,68 @@
|
||||
# Contributing to Motor
|
||||
|
||||
Contributions are encouraged. Please read these guidelines before
|
||||
sending a pull request.
|
||||
|
||||
## Bugfixes and New Features
|
||||
|
||||
Before starting to write code, look for existing tickets or create one
|
||||
in [Jira](https://jira.mongodb.org/browse/MOTOR) for your specific issue
|
||||
or feature request.
|
||||
|
||||
## Running Tests
|
||||
|
||||
Install a recent version of MongoDB and run it on the default port from
|
||||
a clean data directory. Pass "--setParameter enableTestCommands=1" to
|
||||
mongod to enable testing MotorCursor's `max_time_ms` method.
|
||||
|
||||
Control how the tests connect to MongoDB with these environment
|
||||
variables:
|
||||
|
||||
- `DB_IP`: Defaults to "localhost", can be a domain name or IP
|
||||
- `DB_PORT`: Defaults to 27017
|
||||
- `DB_USER`, `DB_PASSWORD`: To test with authentication, create an
|
||||
admin user and set these environment variables to the username and
|
||||
password
|
||||
- `CERT_DIR`: Path with alternate client.pem and ca.pem for testing.
|
||||
Otherwise the suite uses those in test/certificates/.
|
||||
|
||||
Install [tox](https://testrun.org/tox/) and run it from the command line
|
||||
in the repository directory. You will need a variety of Python
|
||||
interpreters installed. For a minimal test, ensure you have your desired
|
||||
Python version on your path, and run:
|
||||
|
||||
```bash
|
||||
tox -m test
|
||||
```
|
||||
|
||||
The doctests pass with Python 3.7+ and a MongoDB 5.0 instance running on
|
||||
port 27017:
|
||||
|
||||
```bash
|
||||
tox -m doctest
|
||||
```
|
||||
|
||||
## Running Linters
|
||||
|
||||
Motor uses [pre-commit](https://pypi.org/project/pre-commit/) for
|
||||
managing linting of the codebase. `pre-commit` performs various checks
|
||||
on all files in Motor and uses tools that help follow a consistent code
|
||||
style within the codebase.
|
||||
|
||||
To set up `pre-commit` locally, run:
|
||||
|
||||
```bash
|
||||
pip install pre-commit # or brew install pre-commit for global install.
|
||||
pre-commit install
|
||||
```
|
||||
To run `pre-commit` manually, run:
|
||||
|
||||
```bash
|
||||
tox -m lint
|
||||
```
|
||||
|
||||
## General Guidelines
|
||||
|
||||
- Avoid backward breaking changes if at all possible.
|
||||
- Write inline documentation for new classes and methods.
|
||||
- Add yourself to doc/contributors.rst :)
|
||||
@ -1,65 +0,0 @@
|
||||
Contributing to Motor
|
||||
=====================
|
||||
|
||||
Contributions are encouraged. Please read these guidelines before sending a
|
||||
pull request.
|
||||
|
||||
Bugfixes and New Features
|
||||
-------------------------
|
||||
|
||||
Before starting to write code, look for existing tickets or create one in `Jira
|
||||
<https://jira.mongodb.org/browse/MOTOR>`_ for your specific issue or feature
|
||||
request.
|
||||
|
||||
Running Tests
|
||||
-------------
|
||||
|
||||
Install a recent version of MongoDB and run it on the default port from a clean
|
||||
data directory. Pass "--setParameter enableTestCommands=1" to mongod to enable
|
||||
testing MotorCursor's ``max_time_ms`` method.
|
||||
|
||||
Control how the tests connect to MongoDB with these environment variables:
|
||||
|
||||
- ``DB_IP``: Defaults to "localhost", can be a domain name or IP
|
||||
- ``DB_PORT``: Defaults to 27017
|
||||
- ``DB_USER``, ``DB_PASSWORD``: To test with authentication, create an admin
|
||||
user and set these environment variables to the username and password
|
||||
- ``CERT_DIR``: Path with alternate client.pem and ca.pem for testing.
|
||||
Otherwise the suite uses those in test/certificates/.
|
||||
|
||||
Install `tox`_ and run it from the command line in the repository directory.
|
||||
You will need a variety of Python interpreters installed. For a minimal test,
|
||||
ensure you have your desired Python version on your path, and run::
|
||||
|
||||
> tox -m test
|
||||
|
||||
The doctests pass with Python 3.7+ and a MongoDB 5.0 instance running on
|
||||
port 27017:
|
||||
|
||||
> tox -m doctest
|
||||
|
||||
.. _tox: https://testrun.org/tox/
|
||||
|
||||
Running Linters
|
||||
---------------
|
||||
|
||||
Motor uses `pre-commit <https://pypi.org/project/pre-commit/>`_
|
||||
for managing linting of the codebase.
|
||||
``pre-commit`` performs various checks on all files in Motor and uses tools
|
||||
that help follow a consistent code style within the codebase.
|
||||
|
||||
To set up ``pre-commit`` locally, run::
|
||||
|
||||
pip install pre-commit
|
||||
pre-commit install
|
||||
|
||||
To run ``pre-commit`` manually, run::
|
||||
|
||||
> tox -m lint
|
||||
|
||||
General Guidelines
|
||||
------------------
|
||||
|
||||
- Avoid backward breaking changes if at all possible.
|
||||
- Write inline documentation for new classes and methods.
|
||||
- Add yourself to doc/contributors.rst :)
|
||||
@ -1,4 +1,4 @@
|
||||
include README.rst
|
||||
include README.md
|
||||
include LICENSE
|
||||
include tox.ini
|
||||
include pyproject.toml
|
||||
@ -19,11 +19,10 @@ recursive-include motor *.pyi
|
||||
recursive-include motor *.typed
|
||||
recursive-include motor *.py
|
||||
|
||||
exclude .flake8
|
||||
exclude .readthedocs.yaml
|
||||
exclude .git-blame-ignore-revs
|
||||
exclude .pre-commit-config.yaml
|
||||
exclude release.sh
|
||||
exclude RELEASE.rst
|
||||
exclude CONTRIBUTING.rst
|
||||
exclude RELEASE.md
|
||||
exclude CONTRIBUTING.md
|
||||
exclude .evergreen/*
|
||||
|
||||
205
README.md
Normal file
205
README.md
Normal file
@ -0,0 +1,205 @@
|
||||
# Motor
|
||||
|
||||
|
||||
|
||||
- Info: Motor is a full-featured, non-blocking [MongoDB](http://mongodb.org/)
|
||||
driver for Python [Tornado](http://tornadoweb.org/) and
|
||||
[asyncio](https://docs.python.org/3/library/asyncio.html) applications.
|
||||
|
||||
- Documentation: Available at
|
||||
[motor.readthedocs.io](https://motor.readthedocs.io/en/stable/)
|
||||
|
||||
- Author: A. Jesse Jiryu Davis
|
||||
|
||||
## About
|
||||
|
||||
Motor presents a coroutine-based API for non-blocking access to MongoDB.
|
||||
The source is [on GitHub](https://github.com/mongodb/motor) and the docs
|
||||
are on [ReadTheDocs](https://motor.readthedocs.io/en/stable/).
|
||||
|
||||
> "We use Motor in high throughput environments, processing tens of
|
||||
> thousands of requests per second. It allows us to take full advantage
|
||||
> of modern hardware, ensuring we utilise the entire capacity of our
|
||||
> purchased CPUs. This helps us be more efficient with computing power,
|
||||
> compute spend and minimises the environmental impact of our
|
||||
> infrastructure as a result."
|
||||
>
|
||||
> --*David Mytton, Server Density*
|
||||
>
|
||||
> "We develop easy-to-use sensors and sensor systems with open source
|
||||
> software to ensure every innovator, from school child to laboratory
|
||||
> researcher, has the same opportunity to create. We integrate Motor
|
||||
> into our software to guarantee massively scalable sensor systems for
|
||||
> everyone."
|
||||
>
|
||||
> --*Ryan Smith, inXus Interactive*
|
||||
|
||||
## Support / Feedback
|
||||
|
||||
For issues with, questions about, or feedback for PyMongo, please look
|
||||
into our [support channels](https://support.mongodb.com/welcome). Please
|
||||
do not email any of the Motor developers directly with issues or
|
||||
questions - you're more likely to get an answer on the
|
||||
[StackOverflow](https://stackoverflow.com/questions/tagged/mongodb)
|
||||
(using a "mongodb" tag).
|
||||
|
||||
## Bugs / Feature Requests
|
||||
|
||||
Think you've found a bug? Want to see a new feature in Motor? Please
|
||||
open a case in our issue management tool, JIRA:
|
||||
|
||||
- [Create an account and login](https://jira.mongodb.org).
|
||||
- Navigate to [the MOTOR
|
||||
project](https://jira.mongodb.org/browse/MOTOR).
|
||||
- Click **Create Issue** - Please provide as much information as
|
||||
possible about the issue type and how to reproduce it.
|
||||
|
||||
Bug reports in JIRA for all driver projects (i.e. MOTOR, CSHARP, JAVA)
|
||||
and the Core Server (i.e. SERVER) project are **public**.
|
||||
|
||||
### How To Ask For Help
|
||||
|
||||
Please include all of the following information when opening an issue:
|
||||
|
||||
- Detailed steps to reproduce the problem, including full traceback, if
|
||||
possible.
|
||||
|
||||
- The exact python version used, with patch level:
|
||||
|
||||
```bash
|
||||
python -c "import sys; print(sys.version)"
|
||||
```
|
||||
|
||||
- The exact version of Motor used, with patch level:
|
||||
|
||||
```bash
|
||||
python -c "import motor; print(motor.version)"
|
||||
```
|
||||
|
||||
- The exact version of PyMongo used, with patch level:
|
||||
|
||||
```bash
|
||||
python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"
|
||||
```
|
||||
|
||||
- The exact Tornado version, if you are using Tornado:
|
||||
|
||||
```bash
|
||||
python -c "import tornado; print(tornado.version)"
|
||||
```
|
||||
|
||||
- The operating system and version (e.g. RedHat Enterprise Linux 6.4,
|
||||
OSX 10.9.5, ...)
|
||||
|
||||
### Security Vulnerabilities
|
||||
|
||||
If you've identified a security vulnerability in a driver or any other
|
||||
MongoDB project, please report it according to the [instructions
|
||||
here](https://mongodb.com/docs/manual/tutorial/create-a-vulnerability-report).
|
||||
|
||||
## Installation
|
||||
|
||||
Motor can be installed with [pip](http://pypi.python.org/pypi/pip):
|
||||
|
||||
```bash
|
||||
pip install motor
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Motor works in all the environments officially supported by Tornado or
|
||||
by asyncio. It requires:
|
||||
|
||||
- Unix (including macOS) or Windows.
|
||||
- [PyMongo](http://pypi.python.org/pypi/pymongo/) >=4.1,<5
|
||||
- Python 3.7+
|
||||
|
||||
Optional dependencies:
|
||||
|
||||
Motor supports same optional dependencies as PyMongo. Required
|
||||
dependencies can be installed along with Motor.
|
||||
|
||||
GSSAPI authentication requires `gssapi` extra dependency. The correct
|
||||
dependency can be installed automatically along with Motor:
|
||||
|
||||
```bash
|
||||
pip install "motor[gssapi]"
|
||||
```
|
||||
|
||||
similarly,
|
||||
|
||||
MONGODB-AWS authentication requires `aws` extra dependency:
|
||||
|
||||
```bash
|
||||
pip install "motor[aws]"
|
||||
```
|
||||
|
||||
Support for mongodb+srv:// URIs requires `srv` extra dependency:
|
||||
|
||||
```bash
|
||||
pip install "motor[srv]"
|
||||
```
|
||||
|
||||
OCSP requires `ocsp` extra dependency:
|
||||
|
||||
```bash
|
||||
pip install "motor[ocsp]"
|
||||
```
|
||||
|
||||
Wire protocol compression with snappy requires `snappy` extra
|
||||
dependency:
|
||||
|
||||
```bash
|
||||
pip install "motor[snappy]"
|
||||
```
|
||||
|
||||
Wire protocol compression with zstandard requires `zstd` extra
|
||||
dependency:
|
||||
|
||||
```bash
|
||||
pip install "motor[zstd]"
|
||||
```
|
||||
|
||||
Client-Side Field Level Encryption requires `encryption` extra
|
||||
dependency:
|
||||
|
||||
```bash
|
||||
pip install "motor[encryption]"
|
||||
```
|
||||
|
||||
You can install all dependencies automatically with the following
|
||||
command:
|
||||
|
||||
```bash
|
||||
pip install "motor[gssapi,aws,ocsp,snappy,srv,zstd,encryption]"
|
||||
```
|
||||
|
||||
See
|
||||
[requirements](https://motor.readthedocs.io/en/stable/requirements.html)
|
||||
for details about compatibility.
|
||||
|
||||
## Examples
|
||||
|
||||
See the [examples on
|
||||
ReadTheDocs](https://motor.readthedocs.io/en/stable/examples/index.html).
|
||||
|
||||
## Documentation
|
||||
|
||||
Motor's documentation is on
|
||||
[ReadTheDocs](https://motor.readthedocs.io/en/stable/).
|
||||
|
||||
Build the documentation with Python 3.7+. Install
|
||||
[sphinx](http://sphinx.pocoo.org/), [Tornado](http://tornadoweb.org/),
|
||||
and [aiohttp](https://github.com/aio-libs/aiohttp), and do
|
||||
`cd doc; make html`.
|
||||
|
||||
## Learning Resources
|
||||
|
||||
- MongoDB Learn - [Python
|
||||
courses](https://learn.mongodb.com/catalog?labels=%5B%22Language%22%5D&values=%5B%22Python%22%5D).
|
||||
- [Python Articles on Developer
|
||||
Center](https://www.mongodb.com/developer/languages/python/).
|
||||
|
||||
## Testing
|
||||
|
||||
Run `python setup.py test`. Tests are located in the `test/` directory.
|
||||
184
README.rst
184
README.rst
@ -1,184 +0,0 @@
|
||||
=====
|
||||
Motor
|
||||
=====
|
||||
|
||||
.. image:: https://raw.github.com/mongodb/motor/master/doc/_static/motor.png
|
||||
|
||||
:Info: Motor is a full-featured, non-blocking MongoDB_ driver for Python
|
||||
Tornado_ and asyncio_ applications.
|
||||
:Documentation: Available at `motor.readthedocs.io <https://motor.readthedocs.io/en/stable/>`_
|
||||
:Author: A\. Jesse Jiryu Davis
|
||||
|
||||
About
|
||||
=====
|
||||
|
||||
Motor presents a coroutine-based API for non-blocking access
|
||||
to MongoDB. The source is `on GitHub <https://github.com/mongodb/motor>`_
|
||||
and the docs are on ReadTheDocs_.
|
||||
|
||||
"We use Motor in high throughput environments, processing tens of thousands
|
||||
of requests per second. It allows us to take full advantage of modern
|
||||
hardware, ensuring we utilise the entire capacity of our purchased CPUs.
|
||||
This helps us be more efficient with computing power, compute spend and
|
||||
minimises the environmental impact of our infrastructure as a result."
|
||||
|
||||
--*David Mytton, Server Density*
|
||||
|
||||
"We develop easy-to-use sensors and sensor systems with open source
|
||||
software to ensure every innovator, from school child to laboratory
|
||||
researcher, has the same opportunity to create. We integrate Motor into our
|
||||
software to guarantee massively scalable sensor systems for everyone."
|
||||
|
||||
--*Ryan Smith, inXus Interactive*
|
||||
|
||||
Support / Feedback
|
||||
==================
|
||||
|
||||
For issues with, questions about, or feedback for PyMongo, please look into
|
||||
our `support channels <https://support.mongodb.com/welcome>`_. Please
|
||||
do not email any of the Motor developers directly with issues or
|
||||
questions - you're more likely to get an answer on the `StackOverflow <https://stackoverflow.com/questions/tagged/mongodb>`_ (using a "mongodb" tag).
|
||||
|
||||
Bugs / Feature Requests
|
||||
=======================
|
||||
|
||||
Think you've found a bug? Want to see a new feature in Motor? Please open a
|
||||
case in our issue management tool, JIRA:
|
||||
|
||||
- `Create an account and login <https://jira.mongodb.org>`_.
|
||||
- Navigate to `the MOTOR project <https://jira.mongodb.org/browse/MOTOR>`_.
|
||||
- Click **Create Issue** - Please provide as much information as possible about the issue type and how to reproduce it.
|
||||
|
||||
Bug reports in JIRA for all driver projects (i.e. MOTOR, CSHARP, JAVA) and the
|
||||
Core Server (i.e. SERVER) project are **public**.
|
||||
|
||||
How To Ask For Help
|
||||
-------------------
|
||||
|
||||
Please include all of the following information when opening an issue:
|
||||
|
||||
- Detailed steps to reproduce the problem, including full traceback, if possible.
|
||||
- The exact python version used, with patch level::
|
||||
|
||||
$ python -c "import sys; print(sys.version)"
|
||||
|
||||
- The exact version of Motor used, with patch level::
|
||||
|
||||
$ python -c "import motor; print(motor.version)"
|
||||
|
||||
- The exact version of PyMongo used, with patch level::
|
||||
|
||||
$ python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"
|
||||
|
||||
- The exact Tornado version, if you are using Tornado::
|
||||
|
||||
$ python -c "import tornado; print(tornado.version)"
|
||||
|
||||
- The operating system and version (e.g. RedHat Enterprise Linux 6.4, OSX 10.9.5, ...)
|
||||
|
||||
Security Vulnerabilities
|
||||
------------------------
|
||||
|
||||
If you've identified a security vulnerability in a driver or any other
|
||||
MongoDB project, please report it according to the `instructions here
|
||||
<https://mongodb.com/docs/manual/tutorial/create-a-vulnerability-report>`_.
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Motor can be installed with `pip <http://pypi.python.org/pypi/pip>`_::
|
||||
|
||||
$ pip install motor
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
Motor works in all the environments officially supported by Tornado or by
|
||||
asyncio. It requires:
|
||||
|
||||
* Unix (including macOS) or Windows.
|
||||
* PyMongo_ >=4.1,<5
|
||||
* Python 3.7+
|
||||
|
||||
Optional dependencies:
|
||||
|
||||
Motor supports same optional dependencies as PyMongo. Required dependencies can be installed
|
||||
along with Motor.
|
||||
|
||||
GSSAPI authentication requires ``gssapi`` extra dependency. The correct
|
||||
dependency can be installed automatically along with Motor::
|
||||
|
||||
$ pip install "motor[gssapi]"
|
||||
|
||||
similarly,
|
||||
|
||||
MONGODB-AWS authentication requires ``aws`` extra dependency::
|
||||
|
||||
$ pip install "motor[aws]"
|
||||
|
||||
Support for mongodb+srv:// URIs requires ``srv`` extra dependency::
|
||||
|
||||
$ pip install "motor[srv]"
|
||||
|
||||
OCSP requires ``ocsp`` extra dependency::
|
||||
|
||||
$ pip install "motor[ocsp]"
|
||||
|
||||
Wire protocol compression with snappy requires ``snappy`` extra dependency::
|
||||
|
||||
$ pip install "motor[snappy]"
|
||||
|
||||
Wire protocol compression with zstandard requires ``zstd`` extra dependency::
|
||||
|
||||
$ pip install "motor[zstd]"
|
||||
|
||||
Client-Side Field Level Encryption requires ``encryption`` extra dependency::
|
||||
|
||||
$ pip install "motor[encryption]"
|
||||
|
||||
You can install all dependencies automatically with the following
|
||||
command::
|
||||
|
||||
$ pip install "motor[gssapi,aws,ocsp,snappy,srv,zstd,encryption]"
|
||||
|
||||
See `requirements <https://motor.readthedocs.io/en/stable/requirements.html>`_
|
||||
for details about compatibility.
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
See the `examples on ReadTheDocs <https://motor.readthedocs.io/en/stable/examples/index.html>`_.
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
Motor's documentation is on ReadTheDocs_.
|
||||
|
||||
Build the documentation with Python 3.7+. Install sphinx_, Tornado_, and aiohttp_,
|
||||
and do ``cd doc; make html``.
|
||||
|
||||
Learning Resources
|
||||
==================
|
||||
|
||||
MongoDB Learn - `Python courses <https://learn.mongodb.com/catalog?labels=%5B%22Language%22%5D&values=%5B%22Python%22%5D>`_.
|
||||
`Python Articles on Developer Center <https://www.mongodb.com/developer/languages/python/>`_.
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
Run ``python setup.py test``.
|
||||
Tests are located in the ``test/`` directory.
|
||||
|
||||
.. _PyMongo: http://pypi.python.org/pypi/pymongo/
|
||||
|
||||
.. _MongoDB: http://mongodb.org/
|
||||
|
||||
.. _Tornado: http://tornadoweb.org/
|
||||
|
||||
.. _asyncio: https://docs.python.org/3/library/asyncio.html
|
||||
|
||||
.. _aiohttp: https://github.com/aio-libs/aiohttp
|
||||
|
||||
.. _ReadTheDocs: https://motor.readthedocs.io/en/stable/
|
||||
|
||||
.. _sphinx: http://sphinx.pocoo.org/
|
||||
71
RELEASE.md
Normal file
71
RELEASE.md
Normal file
@ -0,0 +1,71 @@
|
||||
# Motor Releases
|
||||
|
||||
## Versioning
|
||||
|
||||
Motor's version numbers follow [semantic
|
||||
versioning](http://semver.org/): each version number is structured
|
||||
"major.minor.patch". Patch releases fix bugs, minor releases add
|
||||
features (and may fix bugs), and major releases include API changes that
|
||||
break backwards compatibility (and may add features and fix bugs).
|
||||
|
||||
In between releases we add .devN to the version number to denote the
|
||||
version under development. So if we just released 2.3.0, then the
|
||||
current dev version might be 2.3.1.dev0 or 2.4.0.dev0. When we make the
|
||||
next release we replace all instances of 2.x.x.devN in the docs with the
|
||||
new version number.
|
||||
|
||||
<https://www.python.org/dev/peps/pep-0440/>
|
||||
|
||||
## Release Process
|
||||
|
||||
Motor ships a [pure Python
|
||||
wheel](https://packaging.python.org/guides/distributing-packages-using-setuptools/#pure-python-wheels)
|
||||
and a [source
|
||||
distribution](https://packaging.python.org/guides/distributing-packages-using-setuptools/#source-distributions).
|
||||
|
||||
1. Motor is tested on Evergreen. Ensure that the latest commit is
|
||||
passing CI as expected:
|
||||
<https://evergreen.mongodb.com/waterfall/motor>.
|
||||
|
||||
2. Check JIRA to ensure all the tickets in this version have been
|
||||
completed.
|
||||
|
||||
3. Add release notes to `doc/changelog.rst`. Generally just
|
||||
summarize/clarify the git log, but you might add some more long form
|
||||
notes for big changes.
|
||||
|
||||
4. Replace the `devN` version number w/ the new version number (see
|
||||
note above in [Versioning](#versioning)) in `motor/_version.py`.
|
||||
Commit the change and tag the release. Immediately bump the version
|
||||
number to `dev0` in a new commit:
|
||||
|
||||
$ # Bump to release version number
|
||||
$ git commit -a -m "BUMP <release version number>"
|
||||
$ git tag -a "<release version number>" -m "BUMP <release version number>"
|
||||
$ # Bump to dev version number
|
||||
$ git commit -a -m "BUMP <dev version number>"
|
||||
$ git push
|
||||
$ git push --tags
|
||||
|
||||
5. Bump the version number to `<next version>.dev0` in
|
||||
`motor/_version.py`, commit, then push.
|
||||
|
||||
6. Authorize the deployment for the tagged version on the release
|
||||
GitHub Action and wait for it to successfully publish to PyPI.
|
||||
|
||||
7. Make sure the new version appears on
|
||||
<https://motor.readthedocs.io/>. If the new version does not show up
|
||||
automatically, trigger a rebuild of "latest":
|
||||
<https://readthedocs.org/projects/motor/builds/>
|
||||
|
||||
8. Publish the release version in Jira and add a brief description
|
||||
about the reason for the release or the main feature.
|
||||
|
||||
9. Announce the release on:
|
||||
<https://www.mongodb.com/community/forums/c/announcements/driver-releases>
|
||||
|
||||
10. Create a GitHub Release for the tag using
|
||||
<https://github.com/mongodb/motor/releases/new>. The title should be
|
||||
"Motor X.Y.Z", and the description should contain a link to the
|
||||
release notes on the the community forum, e.g. "Release notes:
|
||||
mongodb.com/community/forums/t/motor-2-5-1-released/120313."
|
||||
67
RELEASE.rst
67
RELEASE.rst
@ -1,67 +0,0 @@
|
||||
==============
|
||||
Motor Releases
|
||||
==============
|
||||
|
||||
Versioning
|
||||
----------
|
||||
|
||||
Motor's version numbers follow `semantic versioning <http://semver.org/>`_:
|
||||
each version number is structured "major.minor.patch". Patch releases fix
|
||||
bugs, minor releases add features (and may fix bugs), and major releases
|
||||
include API changes that break backwards compatibility (and may add features
|
||||
and fix bugs).
|
||||
|
||||
In between releases we add .devN to the version number to denote the version
|
||||
under development. So if we just released 2.3.0, then the current dev
|
||||
version might be 2.3.1.dev0 or 2.4.0.dev0. When we make the next release we
|
||||
replace all instances of 2.x.x.devN in the docs with the new version number.
|
||||
|
||||
https://www.python.org/dev/peps/pep-0440/
|
||||
|
||||
Release Process
|
||||
---------------
|
||||
|
||||
Motor ships a `pure Python wheel <https://packaging.python.org/guides/distributing-packages-using-setuptools/#pure-python-wheels>`_
|
||||
and a `source distribution <https://packaging.python.org/guides/distributing-packages-using-setuptools/#source-distributions>`_.
|
||||
|
||||
#. Motor is tested on Evergreen. Ensure that the latest commit is passing CI as
|
||||
expected: https://evergreen.mongodb.com/waterfall/motor.
|
||||
|
||||
#. Check JIRA to ensure all the tickets in this version have been completed.
|
||||
|
||||
#. Add release notes to ``doc/changelog.rst``. Generally just summarize/clarify
|
||||
the git log, but you might add some more long form notes for big changes.
|
||||
|
||||
#. Replace the ``devN`` version number w/ the new version number (see
|
||||
note above in `Versioning`_) in
|
||||
``motor/_version.py``. Commit the change and tag the release.
|
||||
Immediately bump the version number to ``dev0`` in a new commit::
|
||||
|
||||
$ # Bump to release version number
|
||||
$ git commit -a -m "BUMP <release version number>"
|
||||
$ git tag -a "<release version number>" -m "BUMP <release version number>"
|
||||
$ # Bump to dev version number
|
||||
$ git commit -a -m "BUMP <dev version number>"
|
||||
$ git push
|
||||
$ git push --tags
|
||||
|
||||
#. Bump the version number to ``<next version>.dev0`` in ``motor/_version.py``,
|
||||
commit, then push.
|
||||
|
||||
#. Authorize the deployment for the tagged version on the release GitHub Action and
|
||||
wait for it to successfully publish to PyPI.
|
||||
|
||||
#. Make sure the new version appears on https://motor.readthedocs.io/. If the
|
||||
new version does not show up automatically, trigger a rebuild of "latest":
|
||||
https://readthedocs.org/projects/motor/builds/
|
||||
|
||||
#. Publish the release version in Jira and add a brief description about the reason
|
||||
for the release or the main feature.
|
||||
|
||||
#. Announce the release on:
|
||||
https://www.mongodb.com/community/forums/c/announcements/driver-releases
|
||||
|
||||
#. Create a GitHub Release for the tag using https://github.com/mongodb/motor/releases/new.
|
||||
The title should be "Motor X.Y.Z", and the description should contain a
|
||||
link to the release notes on the the community forum, e.g.
|
||||
"Release notes: mongodb.com/community/forums/t/motor-2-5-1-released/120313."
|
||||
@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
|
||||
name = "motor"
|
||||
dynamic = ["version"]
|
||||
description = "Non-blocking MongoDB driver for Tornado or asyncio"
|
||||
readme = "README.rst"
|
||||
readme = "README.md"
|
||||
license = { file = "LICENSE" }
|
||||
requires-python = ">=3.7"
|
||||
authors = [
|
||||
|
||||
Loading…
Reference in New Issue
Block a user