patch: update developer docs

docs/src/development/conventions/git.md

@@ -1,4 +1,52 @@
-# Git
 
-1. Tell everyone to use GitLens. It's amazing
-2. Outline other standard processes and tools (precommits, hooks, workflows, gitflows etc)
+## Git Conventions
+
+Following a consistent Git workflow is essential for ensuring project clarity and maintaining code quality. Here are some conventions and tools recommended for managing code changes, collaborating with team members, and improving overall workflow efficiency.
+
+1. **Branching Strategy**
+   - **Create Separate Branches for Each Feature or Bug Fix**: Start a new branch for each new feature, bug fix, or task. This keeps changes isolated and organized, making it easier to track work and manage pull requests.
+   - **Use Descriptive Branch Names**: Branch names should be concise but informative, describing the purpose of the branch. Common conventions include:
+     - `feature/<feature-name>` for new features
+     - `bugfix/<issue-description>` for bug fixes
+     - `hotfix/<urgent-fix>` for critical patches
+   - Example:
+     ```bash
+     git checkout -b feature/add-user-authentication
+     ```
+
+2. **Commit Message Conventions**
+   - **Keep Commit Messages Simple and Informative**: Each commit message should describe the changes made in that commit. Standard prefixes are used to provide context:
+     - `feat: <message>` - for a new feature
+     - `fix: <message>` - for a bug fix
+     - `patch: <message>` - for small changes or patches
+     - `refactor: <message>` - for refactoring code without changing functionality
+     - `docs: <message>` - for documentation updates
+     - `test: <message>` - for test-related updates
+   - Example:
+     ```bash
+     git commit -m "feat: add login form and authentication handling"
+     ```
+
+3. **Avoid Too Many Commits in a PR**
+   - Try to group related changes together and avoid committing excessively within a single pull request (PR). Each PR should have a manageable set of commits to make it easier to review. If you accumulate too many commits, consider squashing them into meaningful commits before opening the PR.
+   - However, if necessary, don’t compromise clarity just to reduce commits—clear, granular commits are more important than quantity.
+
+4. **Use GitLens for Visual Studio Code**
+   - GitLens is a powerful Git extension for Visual Studio Code that enhances the Git experience by displaying history, blame annotations, and more. It’s highly recommended for tracking changes and understanding code history effectively.
+   - Install it via VS Code's extension manager for easier navigation and insight into code changes.
+
+5. **Standard Tools and Processes**
+   - **Pre-Commit Hooks**: Use pre-commit hooks to automatically run checks (e.g., linting, testing, or formatting) before commits are accepted. This helps catch issues early in the process.
+     - Example: You can set up a hook to run `black` (for Python) or `eslint` (for JavaScript) on staged files.
+   - **Git Workflows**: Consider using GitFlow or GitHub Flow for managing branches and releases in a structured way. 
+     - **GitFlow**: A branching model for larger projects, organizing development into feature, release, and hotfix branches.
+     - **GitHub Flow**: A simplified workflow ideal for small teams or continuous deployment setups, usually with a single main branch and feature branches.
+   - **Continuous Integration (CI)**: Set up CI pipelines (e.g., GitHub Actions, Jenkins) to automatically run tests and code quality checks whenever new code is pushed or a pull request is opened.
+   - **Code Review Workflow**: Ensure all PRs undergo a code review. This practice encourages knowledge sharing and improves code quality through constructive feedback.
+
+6. **Additional Tips**
+   - **Rebase Before Merging**: Rebase your branch with the latest changes from the main branch to keep history clean and avoid merge conflicts.
+   - **Squash Commits**: If you end up with multiple minor commits (e.g., typo fixes, small adjustments), squash them into meaningful chunks before merging to keep the commit history concise.
+
+By following these conventions and utilizing the suggested tools, the development process remains streamlined and efficient, facilitating collaboration and code consistency across the team.
+

docs/src/development/index.md

@@ -1,16 +1,75 @@
-# Development
 
-> Note that all users, regardless of role, should understand and review the [security](../devops/security/index.md) section.
 
-Kartoza is a consulting and development firm. In many instances, projects require developers to leverage existing tools and codebases, and to work with other organisations in a way that is consistent in their own conventions.
+## Development Lifecycle Overview
 
-This documentation seeks to outline processes and practices so that internal project development and practices within the team remain consistent. Where it is noted that beneficial conventions listed here are not implemented in client projects, recommendations may be made that clients adopt such standards.
+The following steps outline the general development workflow when contributing to a Kartoza project. These practices ensure code consistency, maintainability, and alignment with project conventions and standards.
 
-For the most part, however, it is less a concern of how a particular outcome is achieved, but rather that the result is consistent with the appropriate conventions.
 
-- [Documentation](./documentation/index.md)
-- [Conventions](./conventions/index.md)
-- [Technologies](./technologies/index.md)
-- [Environments](./environments/index.md)
-- [Resources](./resources/index.md)
-- [Testing](./testing/index.md)
+```mermaid
+graph TD
+    A[Receive Repository Link] --> B[Clone Project Locally]
+    B --> C[Set Up Project]
+    C --> D[Configure Environment]
+    D --> E[Run Project Locally]
+    E --> F[Develop Features or Fix Bugs]
+    F --> G[Write/Update Tests]
+    G --> H[Apply Code Standards]
+    H --> I[Create New Branch]
+    I --> J[Push to Remote Repository]
+    J --> K[Open Pull Request]
+```
+
+
+1. **Receive Project Repository Link**  
+   Developers are provided with a GitHub repository link for the project they will be working on.
+
+2. **Clone the Project Locally**  
+   Use Git to clone the project repository to your local machine:
+   ```bash
+   git clone <repository-link>
+   ```
+
+3. **Set Up the Project**  
+   After cloning, follow the installation instructions available in the README file to set up dependencies, tools, and the environment.
+
+4. **Configure Environment Variables**  
+   Adjust the environment variables in `.env` or as instructed in the documentation to ensure proper configuration for local development.
+
+5. **Run the Project Locally**  
+   Start the project to confirm that it runs as expected in your local environment.
+
+6. **Develop New Features or Fix Bugs**  
+   Identify the feature or bug you will be working on and make the necessary code changes. Ensure these changes align with project goals and specifications. You might also want to refer to [Coding Standards](./conventions/coding_standards.md) during the development process.
+
+7. **Write and Update Tests (If Applicable)**  
+   If tests are available, add or update tests to verify that your changes are working as expected. This helps maintain stability and reliability.
+
+8. **Code Formatting and Standards**  
+   Follow PEP 8 (or other specified code style guidelines) to ensure code quality and readability. Use a linter or code formatter to assist with this step.
+
+9. **Create a New Branch for Your Changes**
+
+
+   For Git conventions: [Git](./conventions/git.md)
+
+   Use Git to create a new branch specific to the feature or bug fix:
+   ```bash
+   git checkout -b <branch-name>
+   ```
+
+
+11. **Push Changes to the Remote Repository**  
+    Push your branch to the remote repository on GitHub:
+    ```bash
+    git push origin <branch-name>
+    ```
+
+12. **Open a Pull Request (PR)**  
+    Open a pull request for your branch, describing the changes made. This PR will be reviewed by other team members to ensure code quality and alignment with project requirements. Attach screenshots to the pull request if applicable to show proof of work.
+
+### Important Notes
+- **Security**: All users, regardless of role, should understand and review the [Security](../devops/security/index.md) section.
+- **Consistency with Client Conventions**: Kartoza projects may involve existing tools, codebases, or conventions from other organizations. Follow these practices for consistency with team standards and client expectations.
+
+Kartoza is a consulting and development firm that values consistent, maintainable practices across projects. This documentation outlines the processes to maintain uniformity within the team. Where beneficial conventions are not in place within a client’s project, we may suggest adopting these standards for overall project quality.
+