💤 Note: This project was an early experiment that evolved into something much bigger — Mid Conversation.
BitGeek was a spark — Mid Conversation is the flame. Follow along and see how far we go.

Welcome to BitGeek Software's development standards and project bootstrapping repository! This resource contains everything you need to understand our development practices and get started with a new project.

• 📁 Directory Structure
• 🤝 Contribution Guidelines
• 🎫 Issue Templates
• 📝 Changelog Standards

At BitGeek Software, we prioritize:

• ✨ Code Quality: Maintainable, well-tested, and readable code
• 📚 Documentation: Thorough documentation for all systems and processes
• 🔄 Consistency: Common patterns and practices across all projects
• 🔒 Security: Proactive security measures at every development stage
• 👥 Collaboration: Clear communication and knowledge sharing

Every BitGeek Software project follows a standardized directory structure:

project/
├── app/                         # Main application code
├── docs/                        # Documentation
│   ├── boilerplate/             # Documentation templates
│   └── ...
├── scripts/                     # Application scripts
├── testing/                     # Test files and results
├── .env                         # Environment variables
├── LICENSE                      # License file
├── README.md                    # Main README
├── requirements.txt             # Dependencies
├── VERSION                      # Version file
└── CHANGELOG.md                 # Change log

For detailed directory structure guidelines, see our 📁 Directory Structure Template.

• Python 3.7+
• Git
• Virtual environment tool (venv, pipenv, or conda)

1. Clone this repository as a template:

git clone https://github.com/ronavis/bitgeek-standards.git my-new-project
cd my-new-project

2. Set up a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Initialize the project structure:

python scripts/init_project.py --name "My Project Name"

5. Update the README.md and other documentation files with your project specifics.

All BitGeek Software projects maintain comprehensive documentation:

• README.md: Project overview, quick start, and essential information
• API_ENDPOINTS.md: API documentation when applicable
• CONTRIBUTING.md: Contribution guidelines
• CHANGELOG.md: Record of all notable changes
• Directory READMEs: Purpose explanation for each major directory

Documentation should be written in Markdown and follow our templates in the docs/boilerplate/ directory.

We follow Semantic Versioning:

• MAJOR version (x.0.0): Incompatible API changes
• MINOR version (0.x.0): Backwards-compatible new functionality
• PATCH version (0.0.x): Backwards-compatible bug fixes

All version changes must update:

• VERSION file
• Version badge in README.md
• CHANGELOG.md

After version updates are merged to main, we create and push a Git tag:

git tag -a vX.Y.Z -m "Version X.Y.Z release"
git push origin vX.Y.Z

• All issues/tickets use our standard template
• Ticket IDs follow the pattern: PROJECT-XXX (e.g., AV-175)
• Ad-hoc scripts must reference ticket numbers (e.g., AV-175_improved_verification_guide.py)
• Tickets should contain comprehensive information including implementation details and validation criteria

• Python: Follow PEP 8 guidelines
• Variable names: Use descriptive names in the appropriate style for the language
• Comments: Add comments for complex logic
• Docstrings: Include for all functions and classes
• Dependencies: Always specify versions in requirements files

For schema changes:

• Create a backup of affected tables
• Use ALTER TABLE statements or migrations
• Only drop specific tables if absolutely necessary
• Restore data after schema changes

Example approach:

-- Backup users table
CREATE TABLE users_backup AS SELECT * FROM users;
-- Add new column
ALTER TABLE users ADD COLUMN totp_secret VARCHAR(32) UNIQUE;
-- Restore data if needed
INSERT INTO users SELECT * FROM users_backup;

• Never commit sensitive information (keys, credentials, etc.)
• Use environment variables for configuration
• Implement proper authentication and authorization
• Validate all user inputs
• Follow the principle of least privilege
• Regularly update dependencies to patch security vulnerabilities

• Maintain unit tests for core functionality
• Include integration tests for critical systems
• Automate testing through CI/CD pipelines
• Verify security aspects through dedicated security tests
• Document test requirements for new features

• Internal Wiki
• Style Guide
• Security Checklist
• Deployment Guide

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by BitGeek Software