Merge pull request #38 from Promptly-Technologies-LLC/29-improve-contributing-page-on-documentation-website

Added guidance on code contribution and opening issues

Author: chriscarrollsmith

docs/authentication.qmd

@@ -32,7 +32,7 @@ This template implements a comprehensive authentication system with security bes
 
 The diagrams below show the main authentication flows.
 
-### Registration and login flow
+## Registration and login flow
 
 ``` {python}
 #| echo: false
@@ -87,7 +87,7 @@ auth.render('static/auth_flow', format='png', cleanup=True)
 
 ![Registration and login flow](static/auth_flow.png)
 
-### Password reset flow
+## Password reset flow
 
 ``` {python}
 #| echo: false

docs/contributing.qmd

@@ -4,11 +4,46 @@ title: "Contributing"
 
 ## Contributors
 
-Fork the repository, create a new branch, make your changes, and submit a pull request.
+### Opening issues and bug reports
 
-### Render the documentation
+When opening a new issue or submitting a bug report, please include:
 
-The README and documentation website are rendered with [Quarto](https://quarto.org/docs/). Make changes to the `.qmd` files in the root folder and the `docs` folder. Then run the following commands to render:
+1. A clear, descriptive title
+2. For bug reports:
+   - Description of the expected behavior
+   - Description of the actual behavior
+   - Steps to reproduce the issue
+   - Version information (OS, Python version, package version)
+   - Any relevant error messages or screenshots
+3. For feature requests:
+   - Description of the proposed feature
+   - Use case or motivation for the feature
+   - Any implementation suggestions (optional)
+
+Labels help categorize issues:
+- Use `bug` for reporting problems
+- Use `enhancement` for feature requests
+- Use `documentation` for documentation improvements
+- Use `question` for general queries
+
+### Contributing code
+
+To contribute code to the project:
+
+1. Fork the repository and clone your fork locally
+2. Create a new branch from `main` with a descriptive name
+3. Review the [customization](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/customization.html), [architecture](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/architecture.html), and [authentication](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/authentication.html) pages for guidance on design patterns and code structure and style
+4. Ensure all tests pass, including `mypy` type checking
+5. Stage, commit, and push your changes to the branch:
+   - Use clear, descriptive commit messages
+   - Keep commits focused and atomic
+6. Submit your pull request:
+   - Provide a clear description of the changes
+   - Link to any related issues
+
+### Rendering the documentation
+
+The README and documentation website are rendered with [Quarto](https://quarto.org/docs/). If you ,make changes to the `.qmd` files in the root folder and the `docs` folder, run the following commands to re-render the docs:
 
 ``` bash
 # To render the documentation website
@@ -19,17 +54,22 @@ quarto render index.qmd --output-dir . --output README.md --to gfm
 
 Due to a quirk of Quarto, an unnecessary `index.html` file is created in the root folder when the README is rendered. This file can be safely deleted.
 
+Note that even if your pull request is merged, your changes will not be reflected on the live website until a maintainer republishes the docs.
+
 ## Maintainers
 
-### Increment the version
+### Git flow
 
-Run the following command to increment the version:
+When creating new features,
 
-``` bash
-poetry version patch minor
-```
+1. Open a Github issue with the label `feature` and assign it to yourself.
+2. Create a new branch from the issue sidebar.
+3. Follow the instructions in the popup to check out the branch locally and make your changes on the branch.
+4. Commit your changes and push to the branch.
+5. When you are ready to merge, open a pull request from the branch to main.
+6. Assign someone else for code review.
 
-### Publish the documentation
+### Publishing the documentation
 
 To publish the documentation to GitHub Pages, run the following command: