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..506405f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,111 @@ # 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. + +### 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: + +- 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 `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 +`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 `development` 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 `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. + +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: + - [ ] Add a commit to the copier PR to delete the files from the target repository. +- [ ] 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. 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`.