Skip to content

Commit 8c6a658

Browse files
dacharycdacharyc
authored
Merge pull request #7 from dacharyc/initial-readme
README updates and add issue template
2 parents 5a854cc + a974a31 commit 8c6a658

File tree

5 files changed

+263
-1
lines changed

5 files changed

+263
-1
lines changed

‎.github/ISSUE_TEMPLATE.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
## Issue Description
2+
3+
<!-- Provide a clear and concise description of the issue you're experiencing -->
4+
5+
## Sample App Information
6+
7+
**Which sample app are you using?**
8+
<!-- Check one -->
9+
- [ ] Java (Spring Boot)
10+
- [ ] JavaScript (Express.js)
11+
- [ ] Python (FastAPI)
12+
13+
## Environment Details
14+
15+
**MongoDB Database Version:**
16+
<!-- e.g., 7.0, 8.0, etc. -->
17+
18+
**MongoDB Driver Version:**
19+
<!-- e.g., Java Driver 5.2.0, Node.js Driver 6.10.0, PyMongo 4.10.1, etc. -->
20+
21+
**Deployment Type:**
22+
<!-- Check one -->
23+
- [ ] Local MongoDB instance
24+
- [ ] MongoDB Atlas (cloud)
25+
- [ ] Docker container
26+
- [ ] Other (please specify):
27+
28+
**Operating System:**
29+
<!-- e.g., macOS 14.5, Ubuntu 22.04, Windows 11, etc. -->
30+
31+
**Runtime Version:**
32+
<!-- e.g., Java 17, Node.js 20.11.0, Python 3.11, etc. -->
33+
34+
## Steps to Reproduce
35+
36+
<!-- Provide detailed steps to reproduce the issue -->
37+
38+
1.
39+
2.
40+
3.
41+
42+
## Expected Behavior
43+
44+
<!-- What did you expect to happen? -->
45+
46+
## Actual Behavior
47+
48+
<!-- What actually happened? -->
49+
50+
## Error Messages or Logs
51+
52+
<!-- If applicable, paste any error messages or relevant log output -->
53+
54+
```
55+
<!-- Paste error messages or logs here -->
56+
```
57+
58+
## Additional Context
59+
60+
<!-- Add any other context about the problem here, such as:
61+
- Screenshots
62+
- Configuration files
63+
- Network setup
64+
- Any modifications you made to the sample app
65+
- Links to relevant documentation
66+
-->
67+
68+
## Checklist
69+
70+
Before submitting this issue, please confirm:
71+
72+
- [ ] I have checked the README for setup instructions
73+
- [ ] I have verified my MongoDB connection string is correct
74+
- [ ] I have installed all required dependencies
75+
- [ ] I have searched existing issues to avoid duplicates
76+

‎README.md‎

Lines changed: 109 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,111 @@
11
# Docs Sample Apps
22

3-
A repository of sample applications for the MongoDB documentation.
3+
A repository of sample applications for the MongoDB documentation. This README
4+
describes internal details for the repository maintainers. If you are a developer
5+
having issues with the sample app, please refer to the `Issues` section below.
6+
7+
## Sample Apps
8+
9+
This repository currently contains a single sample app using the `mflix` dataset.
10+
11+
### MFlix Sample App
12+
13+
The sample app provides a Next.js frontend in the `client` directory, with the
14+
choice of three backend stacks in the `server` directory:
15+
16+
- Java: Spring Boot
17+
- JavaScript: Express.js
18+
- Python: FastAPI
19+
20+
```
21+
├── mflix/
22+
│ ├── client/ # Next.js frontend - source for all `mflix` sample app backend repos
23+
│ └── server/
24+
│ ├── express/ # Express.js backend - source for sample-app-nodejs-mflix
25+
│ ├── java-spring/ # Java/Spring backend - source for sample-app-java-mflix
26+
│ └── python/ # Python/FastAPI backend - source for sample-app-python-mflix
27+
├── README.md
28+
├── copier-config.yaml
29+
└── deprecated_examples.json
30+
```
31+
32+
## Artifact Repositories
33+
34+
This repository serves as the source for the following artifact repositories:
35+
36+
- Java: [mongodb/sample-app-java-mflix](https://github.com/mongodb/sample-app-java-mflix)
37+
- JavaScript: [mongodb/sample-app-nodejs-mflix](https://github.com/mongodb/sample-app-nodejs-mflix)
38+
- Python: [mongodb/sample-app-python-mflix](https://github.com/mongodb/sample-app-python-mflix)
39+
40+
## Development
41+
42+
When you merge to `main`, a copier tool copies the source from this repository
43+
to a target repository for each sample app. For configuration details, refer to
44+
`copier-config.yaml`.
45+
46+
### Branching Model
47+
48+
For development, work from the `development` branch. Make incremental PRs
49+
containing new features and bug fixes to `development`, *not* `main`.
50+
51+
When all development work is complete, *then* create a release PR from
52+
`development` to `main`. Upon merging to `main,` the copier tool runs
53+
automatically. It creates a new PR in the target repository, which must be
54+
tested and merged manually.
55+
56+
### Deleting Files
57+
58+
If a PR from `development` to `main` deletes any files, this creates a new
59+
entry in the `deprecated_examples.json` file. This entry resembles:
60+
61+
```json
62+
{
63+
"filename": "go/gcloud24march_v2.go",
64+
"repo": "docs-code-examples-test-target",
65+
"branch": "v2.2",
66+
"deleted_on": "2025-03-24T18:16:30Z"
67+
},
68+
```
69+
70+
The copier tool does not delete files from the target repository. You must
71+
manually delete files from the target repository that are listed in
72+
`deprecated_examples.json`. This is an intentional step to avoid accidentally
73+
deleting files that are referred to in documentation. Review documentation
74+
references before deleting files.
75+
76+
## Release Process
77+
78+
When you merge a release PR from `development` to `main`, the copier tool
79+
creates a new PR in the target repository. This PR must be tested and merged
80+
manually. This is an intentional design choice to ensure:
81+
82+
- The sample app still functions as expected after copying.
83+
- Any documentation references are updated as part of the release process.
84+
85+
To test and verify the PR, navigate to the target repository - see
86+
`Artifact Repositories` above. Perform the following checks:
87+
88+
- [ ] Verify that the PR contains the expected changes.
89+
- [ ] Check out the PR locally.
90+
- [ ] Build and test the changes.
91+
- [ ] Run the tests
92+
- [ ] Run the application and verify that it functions as expected.
93+
- [ ] Review the `deprecated_examples.json` file for any files that need to be
94+
deleted. If files are deleted:
95+
- [ ] Add a commit to the copier PR to delete the files from the target repository.
96+
- [ ] Merge the PR.
97+
98+
## Issues
99+
100+
If you are a developer having issues with the sample app, feel free to open an
101+
issue in this repository. Please include the following information:
102+
103+
- [ ] The sample app you are using (Java, JavaScript, or Python)
104+
- [ ] The version of the MongoDB database you are using
105+
- [ ] The version of the MongoDB driver you are using
106+
- [ ] What type of deployment you're using (local, Atlas, etc.)
107+
- [ ] Any other relevant information that might help us reproduce the issue
108+
109+
## Contributions
110+
111+
We are not currently accepting public contributions to this repository.

‎mflix/README-JAVA-SPRING.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Java Spring Boot MongoDB Sample MFlix Application
2+
3+
[TODO: Add intro]
4+
5+
```
6+
├── README.md
7+
├── client/ # Next.js frontend
8+
└── server/ # Java Spring backend
9+
```
10+
11+
## Getting Started
12+
13+
[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.]
14+
15+
## Issues
16+
17+
If you have problems running the sample app, please check the following:
18+
19+
- [ ] Verify that you have set your MongoDB connection string in the `.env` file.
20+
- [ ] Verify that you have started the Java Spring server.
21+
- [ ] Verify that you have started the Next.js client.
22+
- [ ] Verify that you have no firewalls blocking access to the server or client ports.
23+
24+
If you have verified the above and still have issues, please
25+
[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose)
26+
on the source repository `mongodb/docs-sample-apps`.

‎mflix/README-JAVASCRIPT-EXPRESS.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# JavaScript Express.js MongoDB Sample MFlix Application
2+
3+
[TODO: Add intro]
4+
5+
```
6+
├── README.md
7+
├── client/ # Next.js frontend
8+
└── server/ # Express.js backend
9+
```
10+
11+
## Getting Started
12+
13+
[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.]
14+
15+
## Issues
16+
17+
If you have problems running the sample app, please check the following:
18+
19+
- [ ] Verify that you have set your MongoDB connection string in the `.env` file.
20+
- [ ] Verify that you have started the Express server.
21+
- [ ] Verify that you have started the Next.js client.
22+
- [ ] Verify that you have no firewalls blocking access to the server or client ports.
23+
24+
If you have verified the above and still have issues, please
25+
[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose)
26+
on the source repository `mongodb/docs-sample-apps`.

‎mflix/README-PYTHON-FASTAPI.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Python FastAPI MongoDB Sample MFlix Application
2+
3+
[TODO: Add intro]
4+
5+
```
6+
├── README.md
7+
├── client/ # Next.js frontend
8+
└── server/ # Python FastAPI backend
9+
```
10+
11+
## Getting Started
12+
13+
[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.]
14+
15+
## Issues
16+
17+
If you have problems running the sample app, please check the following:
18+
19+
- [ ] Verify that you have set your MongoDB connection string in the `.env` file.
20+
- [ ] Verify that you have started the Python FastAPI server.
21+
- [ ] Verify that you have started the Next.js client.
22+
- [ ] Verify that you have no firewalls blocking access to the server or client ports.
23+
24+
If you have verified the above and still have issues, please
25+
[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose)
26+
on the source repository `mongodb/docs-sample-apps`.

0 commit comments

Comments
 (0)