From b1c214f6364bc1b07e68a0dcfe979f08697e47e5 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Mon, 27 Oct 2025 11:27:54 -0400 Subject: [PATCH 1/4] Add development details, issue template --- .github/ISSUE_TEMPLATE.md | 76 ++++++++++++++++++++++++++ README.md | 112 +++++++++++++++++++++++++++++++++++++- 2 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..bf7249c --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,76 @@ +## Issue Description + + + +## Sample App Information + +**Which sample app are you using?** + +- [ ] Java (Spring Boot) +- [ ] JavaScript (Express.js) +- [ ] Python (FastAPI) + +## Environment Details + +**MongoDB Database Version:** + + +**MongoDB Driver Version:** + + +**Deployment Type:** + +- [ ] Local MongoDB instance +- [ ] MongoDB Atlas (cloud) +- [ ] Docker container +- [ ] Other (please specify): + +**Operating System:** + + +**Runtime Version:** + + +## Steps to Reproduce + + + +1. +2. +3. + +## Expected Behavior + + + +## Actual Behavior + + + +## Error Messages or Logs + + + +``` + +``` + +## Additional Context + + + +## Checklist + +Before submitting this issue, please confirm: + +- [ ] I have checked the README for setup instructions +- [ ] I have verified my MongoDB connection string is correct +- [ ] I have installed all required dependencies +- [ ] I have searched existing issues to avoid duplicates + diff --git a/README.md b/README.md index b18b53b..a6c3d64 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,113 @@ # Docs Sample Apps -A repository of sample applications for the MongoDB documentation. \ No newline at end of file +A repository of sample applications for the MongoDB documentation. This README +describes internal details for the repository maintainers. If you are a developer +having issues with the sample app, please refer to the `Issues` section below. + +## Sample Apps + +This repository currently contains a single sample app using the `mflix` dataset. +The sample app provides a Next.js frontend in the `client` directory, with the +choice of three backend stacks in the `server` directory: + +- Java: Spring Boot +- JavaScript: Express.js +- Python: FastAPI + +``` +├── mflix/ +│ ├── client/ # Next.js frontend - source for all `mflix` sample app backend repos +│ └── server/ +│ ├── express/ # Express.js backend - source for sample-app-nodejs-mflix +│ ├── java-spring/ # Java/Spring backend - source for sample-app-java-mflix +│ └── python/ # Python/FastAPI backend - source for sample-app-python-mflix +├── README.md +├── copier-config.yaml +└── deprecated_examples.json +``` + +## Artifact Repositories + +This repository serves as the source for the following artifact repositories: + +- Java: [mongodb/sample-app-java-mflix](https://github.com/mongodb/sample-app-java-mflix) +- JavaScript: [mongodb/sample-app-nodejs-mflix](https://github.com/mongodb/sample-app-nodejs-mflix) +- Python: [mongodb/sample-app-python-mflix](https://github.com/mongodb/sample-app-python-mflix) + +## Development + +When you merge to `main`, a copier tool copies the source from this repository +to a target repository for each sample app. For configuration details, refer to +`copier-config.yaml`. + +### Branching Model + +For development, work from the `develop` branch. Make incremental PRs containing +new features and bug fixes to `develop`, *not* `main`. + +When all development work is complete, *then* create a release PR from +`develop` to `main`. Upon merging to `main,` the copier tool runs automatically. +It creates a new PR in the target repository, which must be tested and merged +manually. + +### Deleting Files + +If a PR from `develop` to `main` deletes any files, this creates a new entry in +the `deprecated_examples.json` file. This entry resembles: + +```json +{ + "filename": "go/gcloud24march_v2.go", + "repo": "docs-code-examples-test-target", + "branch": "v2.2", + "deleted_on": "2025-03-24T18:16:30Z" +}, +``` + +The copier tool does not delete files from the target repository. You must +manually delete files from the target repository that are listed in +`deprecated_examples.json`. This is an intentional step to avoid accidentally +deleting files that are referred to in documentation. Review documentation +references before deleting files. + +## Release Process + +When you merge a release PR from `develop` to `main`, the copier tool creates a +new PR in the target repository. This PR must be tested and merged manually. +This is an intentional design choice to ensure: + +- The sample app still functions as expected after copying. +- Any documentation references are updated as part of the release process. + +To test and verify the PR, navigate to the target repository - see +`Artifact Repositories` above. Perform the following checks: + +- [ ] Verify that the PR contains the expected changes. +- [ ] Check out the PR locally. + - [ ] Build and test the changes. + - [ ] Run the tests + - [ ] Run the application and verify that it functions as expected. +- [ ] Review the `deprecated_examples.json` file for any files that need to be + deleted. If files are deleted: + - [ ] Review documentation references to ensure that any deleted files are not + referred to. If they are, update the documentation to refer to the correct + file. + - [ ] Add a commit to the copier PR to delete the files from the target repository. +- [ ] If the PR is for a new version of an existing sample app, update the + documentation to refer to the new version. +- [ ] Merge the PR. + +## Issues + +If you are a developer having issues with the sample app, feel free to open an +issue in this repository. Please include the following information: + +- [ ] The sample app you are using (Java, JavaScript, or Python) +- [ ] The version of the MongoDB database you are using +- [ ] The version of the MongoDB driver you are using +- [ ] What type of deployment you're using (local, Atlas, etc.) +- [ ] Any other relevant information that might help us reproduce the issue + +## Contributions + +We are not currently accepting public contributions to this repository. From 6d8149676b427272aa40b6d1075a341a6ab427df Mon Sep 17 00:00:00 2001 From: dacharyc Date: Mon, 27 Oct 2025 11:54:24 -0400 Subject: [PATCH 2/4] Scaffold READMEs for the projects with info about reporting issues --- mflix/README-JAVA-SPRING.md | 26 ++++++++++++++++++++++++++ mflix/README-JAVASCRIPT-EXPRESS.md | 26 ++++++++++++++++++++++++++ mflix/README-PYTHON-FASTAPI.md | 26 ++++++++++++++++++++++++++ 3 files changed, 78 insertions(+) create mode 100644 mflix/README-JAVA-SPRING.md create mode 100644 mflix/README-JAVASCRIPT-EXPRESS.md create mode 100644 mflix/README-PYTHON-FASTAPI.md diff --git a/mflix/README-JAVA-SPRING.md b/mflix/README-JAVA-SPRING.md new file mode 100644 index 0000000..19db73d --- /dev/null +++ b/mflix/README-JAVA-SPRING.md @@ -0,0 +1,26 @@ +# Java Spring Boot MongoDB Sample MFlix Application + +[TODO: Add intro] + +``` +├── README.md +├── client/ # Next.js frontend +└── server/ # Java Spring backend +``` + +## Getting Started + +[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.] + +## Issues + +If you have problems running the sample app, please check the following: + +- [ ] Verify that you have set your MongoDB connection string in the `.env` file. +- [ ] Verify that you have started the Java Spring server. +- [ ] Verify that you have started the Next.js client. +- [ ] Verify that you have no firewalls blocking access to the server or client ports. + +If you have verified the above and still have issues, please +[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose) +on the source repository `mongodb/docs-sample-apps`. diff --git a/mflix/README-JAVASCRIPT-EXPRESS.md b/mflix/README-JAVASCRIPT-EXPRESS.md new file mode 100644 index 0000000..fa79f86 --- /dev/null +++ b/mflix/README-JAVASCRIPT-EXPRESS.md @@ -0,0 +1,26 @@ +# JavaScript Express.js MongoDB Sample MFlix Application + +[TODO: Add intro] + +``` +├── README.md +├── client/ # Next.js frontend +└── server/ # Express.js backend +``` + +## Getting Started + +[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.] + +## Issues + +If you have problems running the sample app, please check the following: + +- [ ] Verify that you have set your MongoDB connection string in the `.env` file. +- [ ] Verify that you have started the Express server. +- [ ] Verify that you have started the Next.js client. +- [ ] Verify that you have no firewalls blocking access to the server or client ports. + +If you have verified the above and still have issues, please +[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose) +on the source repository `mongodb/docs-sample-apps`. diff --git a/mflix/README-PYTHON-FASTAPI.md b/mflix/README-PYTHON-FASTAPI.md new file mode 100644 index 0000000..229462f --- /dev/null +++ b/mflix/README-PYTHON-FASTAPI.md @@ -0,0 +1,26 @@ +# Python FastAPI MongoDB Sample MFlix Application + +[TODO: Add intro] + +``` +├── README.md +├── client/ # Next.js frontend +└── server/ # Python FastAPI backend +``` + +## Getting Started + +[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.] + +## Issues + +If you have problems running the sample app, please check the following: + +- [ ] Verify that you have set your MongoDB connection string in the `.env` file. +- [ ] Verify that you have started the Python FastAPI server. +- [ ] Verify that you have started the Next.js client. +- [ ] Verify that you have no firewalls blocking access to the server or client ports. + +If you have verified the above and still have issues, please +[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose) +on the source repository `mongodb/docs-sample-apps`. From 70c379b7ced9cba16a682c68b86020658ebd1794 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Mon, 27 Oct 2025 11:57:00 -0400 Subject: [PATCH 3/4] Update to use the branch name Jordan has unified on --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a6c3d64..a5709c9 100644 --- a/README.md +++ b/README.md @@ -42,18 +42,18 @@ to a target repository for each sample app. For configuration details, refer to ### Branching Model -For development, work from the `develop` branch. Make incremental PRs containing -new features and bug fixes to `develop`, *not* `main`. +For development, work from the `development` branch. Make incremental PRs +containing new features and bug fixes to `development`, *not* `main`. When all development work is complete, *then* create a release PR from -`develop` to `main`. Upon merging to `main,` the copier tool runs automatically. -It creates a new PR in the target repository, which must be tested and merged -manually. +`development` to `main`. Upon merging to `main,` the copier tool runs +automatically. It creates a new PR in the target repository, which must be +tested and merged manually. ### Deleting Files -If a PR from `develop` to `main` deletes any files, this creates a new entry in -the `deprecated_examples.json` file. This entry resembles: +If a PR from `development` to `main` deletes any files, this creates a new +entry in the `deprecated_examples.json` file. This entry resembles: ```json { @@ -72,9 +72,9 @@ references before deleting files. ## Release Process -When you merge a release PR from `develop` to `main`, the copier tool creates a -new PR in the target repository. This PR must be tested and merged manually. -This is an intentional design choice to ensure: +When you merge a release PR from `development` to `main`, the copier tool +creates a new PR in the target repository. This PR must be tested and merged +manually. This is an intentional design choice to ensure: - The sample app still functions as expected after copying. - Any documentation references are updated as part of the release process. From a974a312eba10e1047a087a830e7f038ec758ec7 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 28 Oct 2025 14:52:52 -0400 Subject: [PATCH 4/4] Apply suggestions from review --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a5709c9..506405f 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ having issues with the sample app, please refer to the `Issues` section below. ## Sample Apps This repository currently contains a single sample app using the `mflix` dataset. + +### MFlix Sample App + The sample app provides a Next.js frontend in the `client` directory, with the choice of three backend stacks in the `server` directory: @@ -89,12 +92,7 @@ To test and verify the PR, navigate to the target repository - see - [ ] Run the application and verify that it functions as expected. - [ ] Review the `deprecated_examples.json` file for any files that need to be deleted. If files are deleted: - - [ ] Review documentation references to ensure that any deleted files are not - referred to. If they are, update the documentation to refer to the correct - file. - [ ] Add a commit to the copier PR to delete the files from the target repository. -- [ ] If the PR is for a new version of an existing sample app, update the - documentation to refer to the new version. - [ ] Merge the PR. ## Issues