Dev docs

Author: cybermaggedon

community/contributing.md

@@ -18,3 +18,13 @@ If you are happy to proceed with this agreement you can create a
 pull-request.  The pull-request will stall until you automatically sign
 the contributor agreement.
 
+## Development Process
+
+For detailed information about the development workflow, including:
+- Git branching strategy and release process
+- Testing environment setup
+- Working with AI assistants during development
+- Best practices for modular development
+
+Please see the [Developer Guide](developer.md).
+

community/developer.md

@@ -148,3 +148,95 @@ You can then use a `docker-compose.yaml` file to run them.  Such a file
 can be created from the TrustGraph config utility or the
 `trustgraph-templates` utility repo.
 
+## Development Workflow
+
+### Working with AI Assistants
+
+When working with AI assistants like Claude for development.
+
+Be aware...
+- AI assistants are not perfect.  Your job is to learn their limitations
+  and work with them.
+- Assistants can be forgetful, so "writing things down" is a good plan.
+  Submit a tech spec along with your pull request, and other people will be
+  able to use AI assistants to enchance, test, and verify your work.
+- Assistants can get confused with large quantities of stuff.  So get them
+  to be modular. Bring things into well-defined classes and modules
+  reduces the need to "know everything" at once.
+- AI assistants are a little random and can 'go off-pieste' if things
+  get confusing, so catch them before they do this to save yourself a bunch
+  of time.
+- Try to get an understanding of how things are solved in the codebase to
+  prevent assistants from re-inventing the wheel regarding something that's
+  already solved in the codebase.
+
+A useful process guide:
+1. **Read the Test Strategy**: Have the AI assistant read `TEST_STRATEGY.md`
+   to understand testing approaches
+2. **Branch from Latest Release**: Fork the repo and create a branch off the
+   latest `release/vX.Y`
+3. **Create Technical Specifications**: Get the assistant to write tech
+   specs in `docs/tech-specs/WHATEVER.md` for new features.  It helps to be
+   iterative for complex work.  Start with an empty template and add
+   requirements a bit at time, and check the assistant is doing the right
+   thing.  Shout on the Discord forum if you want something reviewed.
+4. **Iterative Development**: Review and refine the tech spec before
+   implementation.
+5. **Commit the Tech Spec**: Save the specification before beginning
+   implementation.
+6. **Implement with Regular Commits**: Commit changes regularly to bank
+   progress and enable easy rollbacks.
+7. **Create Pull Requests**: Push changes and create PRs for review, do this
+   as your code becomes more mature so you get an idea what the test suite
+   thinks of your change.
+8. **Verify Tests**: Ensure all tests pass before merging.
+9. **Write Tests for New Features**: Add comprehensive tests for any new
+   functionality.
+
+### Testing Environment Setup
+
+For local testing, set up a Python virtual environment in the trustgraph directory:
+
+```bash
+python3 -m venv env
+source env/bin/activate  # On Linux/Mac
+# or
+env\Scripts\activate     # On Windows
+
+pip install ./trustgraph-base
+pip install ./trustgraph-cli
+pip install ./trustgraph-flow
+pip install ./trustgraph-vertexai
+pip install ./trustgraph-bedrock
+
+# Run tests
+pytest tests -m 'not slow'
+```
+
+Note: As we use the 'trustgraph' namespace across multiple packages,
+`pip install -e` seems not to work well.
+
+**Important Notes:**
+- Reinstall packages (`pip install ./package-name`) whenever code changes
+- Run tests periodically to catch issues early
+- AI assistants may not remember to reinstall packages, so monitor this manually
+
+It can save time and token usage by running the tests yourself and
+cut'n'pasting just the errors into the code assistant.
+
+### Development Best Practices
+
+- **Modular Code**: Write modular, well-architected code - this helps both AI
+  assistants and human developers
+- **Incremental Progress**: AI assistants aren't perfect, so encourage
+  incremental changes
+- **Regular Testing**: Test frequently to prevent major issues
+- **Clear Specifications**: Document intentions clearly in tech specs before
+  implementation
+- **Solve common problems** commonly.  As well as all the old-school
+  benefits, this really does save a ton of time and token usage
+
+### Share your experiences
+
+We love Claude and Qwen coding models, we want to hear about your experiences
+too, get in Discord and share.