Revised README #222

Jibola · 2025-01-17T05:34:35Z

README containing a few directives.

How to install
Quickstart
Capabilities
Issues & Help

timgraham · 2025-01-17T13:53:56Z

I envisioned a README similar to Django's and moving most of the other content to docs/.

aclark4life · 2025-01-17T14:29:36Z

I envisioned a README with less than 50 lines 😄 The only reason to say more is if we're catering to a non-Django audience (which we are). But I wouldn't say it here, I would link to the quick start.

Django MongoDB Backend

Installation

Note

Django is a dependency of Django MongoDB Backend and will be installed along with Django MongoDB Backend.

pip install django-mongodb-backend

Usage

Create project

django-admin startproject mysite --template \
    https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip

Run server

Note

MongoDB should be running locally before you start Django.

python manage.py runserver

Open Django

Now open http://127.0.0.1:8000!

timgraham · 2025-01-27T19:00:12Z

README.md

+
+  - Support ArrayFields containing Embedded Models  
+  - Support Collections with multiple Django Models  
+  - Possible support for additional Django fields such as ImageField


ImageField works fine

timgraham · 2025-01-27T19:07:20Z

README.md


-class MongoAdminConfig(AdminConfig):
-    default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"
+This tutorial shows you how to create a Django project, connect to a MongoDB cluster hosted on MongoDB Atlas, and interact with data in your cluster. To read more, please check our MongoDB Backend for Django tutorials page.


I wouldn't call this a tutorial (it's too short and not very detailed).
Please wrap lines at 80 characters.
This project is called "Django MongoDB Backend" not "MongoDB Backend for Django".
Where is the tutorials page?

Yeah, removing that language outright.

timgraham · 2025-01-27T19:09:47Z

README.md

-
-Alternatively, you can use the following `startapp` template which includes
-this change:
+Where `<CONNECTION_STRING_URI>` is your connection string from the previous step.


What previous step?

timgraham · 2025-01-28T19:50:13Z

README.md


-### Specifying the default primary key field
+### Resources


Don't think "Resources" fits as a subheading of "Install"

timgraham · 2025-01-28T19:54:51Z

README.md

@@ -4,247 +4,148 @@ This backend is currently in development and is not advised for Production workf
 changes may be made without notice. We welcome your feedback as we continue to
 explore and build. The best way to share this is via our [MongoDB Community Forum](https://www.mongodb.com/community/forums/tag/python)


missing period

timgraham · 2025-01-28T19:55:05Z

README.md


 The development version of this package supports Django 5.0.x. To install it:

-`pip install git+https://github.com/mongodb-labs/django-mongodb-backend`
+`pip install django-mongodb-backend`


Proposed text:

Use the version of django-mongodb-backend that corresponds to your version of Django. For example, to get the latest compatible release for Django 5.0.x: `pip install --pre django-mongodb-backend==5.2.*` (Until the package is out of beta, you must use pip's `--pre` option.)

timgraham · 2025-01-28T19:55:45Z

README.md


-In your Django settings, you must specify that all models should use
-`ObjectIdAutoField`.
+ Check back soon as we aim to provide more links that will dive deeper into our library!


Don't think the readme would be the place to check. How about a pointer to the documentation instead? (not here, probably)

timgraham · 2025-01-28T19:57:14Z

README.md


-### Configuring migrations
+### Connect to the Database


"database" (not a proper noun)

timgraham · 2025-01-28T20:17:36Z

README.md

+
+  - Querying API powered through the amazing MongoDB Aggregation Pipeline  
+  - Supports most functions of the Django QuerySet API  
+  - Support Query Annotations and common SQL AGGREGATE operators  


What are "Query Annotations"? What does it mean to support SQL aggregate operators on MongoDB? I guess you mean QuerySet.annotate() and QuerySet.aggregate()... you already said most of the QuerySet API is supported....

timgraham · 2025-01-28T20:18:15Z

README.md

-#### `django_mongodb_backend.parse_uri(uri, conn_max_age=0, test=None)`
+- **Management Commands**  
+
+  - Use commands like `migrate`, `makemigrations`, `flush`, `sqlmigrate`, many more.


You already mentioned support for schema management. I don't think management commands need a special callout. Particularly not flush.

timgraham · 2025-01-28T20:20:13Z

README.md

+- **Model MongoDB Documents Through Django’s ORM**  
+
+  - Translate Django model instances to MongoDB documents.  
+  - Create new collections corresponding to models.  


This point is duplicated by "Supports core migration functionalities" below.

timgraham · 2025-01-28T20:21:44Z

README.md

+
+  - Translate Django model instances to MongoDB documents.  
+  - Create new collections corresponding to models.  
+  - Supports field validation, data storage, updating, and deletion.  


"data storage, updating, and deletion" Is this taking about models again? Is "field validation" talking about Django's form validation?

timgraham · 2025-01-28T20:22:36Z

README.md

-`mongodb://` prefix is never required.
+- **Model MongoDB Documents Through Django’s ORM**  
+
+  - Translate Django model instances to MongoDB documents.  


Translate is a strange work. How about "Store Django model instances as MongoDB documents."?

timgraham · 2025-01-28T21:36:29Z

README.md

+
+  - **Unavailable Fields**:
+    - `GeneratedField`
+    - `ImageField`


ImageField is supported

timgraham · 2025-01-28T21:37:43Z

README.md

+- **Django Management Commands that do not work**
+  - `createcachetable`
+  - `inspectdb`
+  - `optimizemigration`


optimizemigration works (has nothing to do with the database backend)

timgraham · 2025-01-28T21:38:27Z

README.md

+  - `inspectdb`
+  - `optimizemigration`
+  - `sqlflush`
+  - `sqlsequencereset`


sqlsequencereset is not applicable since this backend doesn't support AutoField.

timgraham · 2025-01-28T21:41:04Z

README.md

- Check back soon as we aim to provide more links that will dive deeper into our library!
-
-* [Developer Notes](DEV_NOTES.md)
+`pip install django-mongodb-backend~=5.0.0`


I don't believe this works (or is what we want people to use). Did you see the version I proposed?

$ pip install django-mongodb-backend~=5.0.0 ERROR: Could not find a version that satisfies the requirement django-mongodb-backend~=5.0.0 (from versions: 5.0.0a1, 5.0.0a2, 5.0.0a3) [notice] A new release of pip is available: 24.3.1 -> 25.0 [notice] To update, run: pip install --upgrade pip ERROR: No matching distribution found for django-mongodb-backend~=5.0.0

Hadn't seen all the comments yet. Reviewing everything now and applying appropriate changes.

timgraham · 2025-01-28T21:41:47Z

README.md

  - Supports most functions of the Django QuerySet API  
  - Support Query Annotations and common SQL AGGREGATE operators  
-  - We support foreign keys and execute JOIN operations all in 1 database call  
-  - Through our custom raw\_aggregate call, MQL operations like Vector Search, Atlas Search, and GeoSpatial querying still yield Django QuerySet results\!
+   Support foreign key usage and execute JOIN operations


I think "Supports" is the verb tense to use. Dash was inadvertently deleted. Add period.

timgraham · 2025-01-28T21:50:47Z

README.md

- **Management Commands**  
-
-  - Use commands like `migrate`, `makemigrations`, `flush`, `sqlmigrate`, many more.
+- Database Variables `ATOMIC_REQUESTS`, `AUTOCOMMIT`, `CONN_HEALTH_CHECKS`, `TIME_ZONE` not supported


variables -> settings
add period.
"are not"

timgraham · 2025-01-28T21:51:02Z

README.md

-
-  - Use commands like `migrate`, `makemigrations`, `flush`, `sqlmigrate`, many more.
+- Database Variables `ATOMIC_REQUESTS`, `AUTOCOMMIT`, `CONN_HEALTH_CHECKS`, `TIME_ZONE` not supported
+- No support for GeoDjango


"is not supported."

timgraham · 2025-01-28T21:51:12Z

README.md

-  - Use commands like `migrate`, `makemigrations`, `flush`, `sqlmigrate`, many more.
+- Database Variables `ATOMIC_REQUESTS`, `AUTOCOMMIT`, `CONN_HEALTH_CHECKS`, `TIME_ZONE` not supported
+- No support for GeoDjango
+- Functions such as `Chr`, `ExtractQuarter`, `MD5`, `Now`, `Ord`, `Pad`, `Repeat`, `Reverse`, `Right`, `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512`, and `Sign`.


Database functions ... are not supported.

timgraham · 2025-01-28T21:52:05Z

README.md

+- No support for GeoDjango
+- Functions such as `Chr`, `ExtractQuarter`, `MD5`, `Now`, `Ord`, `Pad`, `Repeat`, `Reverse`, `Right`, `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512`, and `Sign`.
+- The `tzinfo` parameter of the `Trunc` database functions does not work properly because MongoDB converts the result back to UTC.
+- Schema Validation is not enforced. Refer to MongoDB documentation for how to enforce schema validation.


Nobody said it was supported. Give a more helpful pointer if this really needs to be said?

Nobody said it was supported. Give a more helpful pointer if this really needs to be said?

I'd definitely prefer linking to unsupported features rather than listing them here.

timgraham · 2025-01-28T21:52:58Z

README.md

@@ -89,10 +76,64 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess
  - Fully integrated with Django's authentication framework.  
  - Supports native user management features like creating users and sessions.

+## Limitations of django-mongodb-backend


"Django MongoDB Backend"

aclark4life

Aren't we moving the contents of DEV_NOTES.md to Sphinx. I'd suggest we don't start adding additional Markdown files unless there is a precedent to do so. E.g. CONTRIBUTING.md

timgraham · 2025-01-28T22:05:11Z

Aren't we moving the contents of DEV_NOTES.md to Sphinx. I'd suggest we don't start adding additional Markdown files unless there is a precedent to do so. E.g. CONTRIBUTING.md

That's my plan. Not going to worry about it for this PR. Think the plan changed since those comments in the PR description was written.

README.md

timgraham · 2025-01-29T02:26:36Z

README.md

-this change:
+From your shell, run the following command to create a new Django project
+called example based on a custom template. Make sure the version referenced
+from `django-mongodb-labs` corresponds to your version of Django similar


I guss you meant "django-mongodb-project" but I'm not quite sure what "from ...." means. I would kind of understand if it said "after" although there is some other stuff between that text and the version number.

I'm not sure referencing the install stage is completely clear. The instruction use "5.0.*" there. I thought what I wrote before - referencing "5.0" specifically - make it clear that the "x" does not need to be changed.

I went ahead and rewrote it to explain that we have a custom template and then explicitly stated that 5.0.x.zip is the thing to pay attention to.

README.md

Revised README

e1586f4

Jibola marked this pull request as draft January 17, 2025 05:34

revised docs

3234a85

timgraham reviewed Jan 27, 2025

View reviewed changes

timgraham reviewed Jan 28, 2025

View reviewed changes

revisions to readme. Included limitations. removed marketing cruft

f869a30

timgraham reviewed Jan 28, 2025

View reviewed changes

aclark4life reviewed Jan 28, 2025

View reviewed changes

removed DEV_NOTES and paired down README

846c98f

timgraham approved these changes Jan 29, 2025

View reviewed changes