1  // SPDX-License-Identifier: AGPL-3.0-or-later
  2  // SPDX-FileCopyrightText: 2024-2025 hyperpolymath
  3  
  4  # Contributing to Oikos Bot
  5  
  6  Thank you for your interest in contributing to Oikos Bot! This document provides guidelines and information for contributors.
  7  
  8  ## Code of Conduct
  9  
 10  By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
 11  
 12  ## Getting Started
 13  
 14  ### Prerequisites
 15  
 16  - Deno 2.1+
 17  - Git
 18  - For full development: GHC 9.4+, OCaml 4.14+, Rust (stable)
 19  
 20  ### Development Setup
 21  
 22  ```bash
 23  # Clone the repository
 24  git clone https://github.com/hyperpolymath/oikos-bot.git
 25  cd oikos-bot
 26  
 27  # Using Guix (recommended)
 28  guix shell -m guix/manifest.scm
 29  
 30  # Using Nix
 31  nix develop
 32  
 33  # Or manually install dependencies
 34  ```
 35  
 36  ### Building
 37  
 38  ```bash
 39  # Bot integration (ReScript + Deno)
 40  cd bot-integration
 41  npm install  # Only for ReScript compiler
 42  deno task build:rescript
 43  
 44  # Run locally
 45  deno task dev
 46  ```
 47  
 48  ## Language Policy
 49  
 50  Oikos Bot follows the **Hyperpolymath Language Standard**:
 51  
 52  ### Allowed Languages
 53  
 54  | Language | Use Case |
 55  |----------|----------|
 56  | ReScript | Primary application code |
 57  | Deno | Runtime & package management |
 58  | Rust | Performance-critical, systems |
 59  | Haskell | Code analysis engine |
 60  | OCaml | Documentation analyzer |
 61  | Guile Scheme | Configuration (STATE.scm, META.scm) |
 62  | Bash/POSIX | Scripts, automation (minimal) |
 63  
 64  ### Not Permitted
 65  
 66  - TypeScript (use ReScript instead)
 67  - Node.js/npm/Bun (use Deno instead)
 68  - Go (use Rust instead)
 69  - Python (except for DeepProbLog policy engine)
 70  
 71  ## How to Contribute
 72  
 73  ### Reporting Bugs
 74  
 75  1. Check existing issues to avoid duplicates
 76  2. Use the bug report template
 77  3. Include:
 78     - Clear description of the bug
 79     - Steps to reproduce
 80     - Expected vs actual behavior
 81     - Environment details (OS, versions)
 82  
 83  ### Suggesting Features
 84  
 85  1. Check existing issues and discussions
 86  2. Use the feature request template
 87  3. Explain the use case and benefit
 88  
 89  ### Pull Requests
 90  
 91  1. **Fork** the repository
 92  2. **Create a branch** from `main`:
 93     ```bash
 94     git checkout -b feature/your-feature-name
 95     ```
 96  3. **Make changes** following our coding standards
 97  4. **Test** your changes:
 98     ```bash
 99     cd bot-integration && deno task test
100     ```
101  5. **Commit** with clear messages:
102     ```bash
103     git commit -m "feat: add eco-score visualization"
104     ```
105  6. **Push** and create a PR
106  
107  ### Commit Messages
108  
109  Follow [Conventional Commits](https://www.conventionalcommits.org/):
110  
111  - `feat:` New feature
112  - `fix:` Bug fix
113  - `docs:` Documentation
114  - `refactor:` Code refactoring
115  - `test:` Tests
116  - `chore:` Maintenance
117  
118  ### Code Style
119  
120  - **ReScript**: Follow ReScript best practices
121  - **Deno**: Use `deno fmt` and `deno lint`
122  - **Haskell**: Use `ormolu` for formatting
123  - **OCaml**: Use `ocamlformat`
124  - **All files**: Include SPDX headers
125  
126  ```
127  // SPDX-License-Identifier: AGPL-3.0-or-later
128  // SPDX-FileCopyrightText: 2024-2025 hyperpolymath
129  ```
130  
131  ## Architecture Overview
132  
133  ```
134  oikos-bot/
135  ├── analyzers/
136  │   ├── code-haskell/    # Haskell code analyzer
137  │   └── docs-ocaml/      # OCaml documentation analyzer
138  ├── bot-integration/     # ReScript + Deno webhooks
139  ├── policy-engine/       # Datalog + DeepProbLog
140  ├── containers/          # Container definitions
141  ├── guix/                # Guix package definitions
142  └── nix/                 # Nix flake
143  ```
144  
145  See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed design.
146  
147  ## Testing
148  
149  ### Running Tests
150  
151  ```bash
152  # Bot integration
153  cd bot-integration
154  deno task test
155  
156  # Haskell analyzer
157  cd analyzers/code-haskell
158  cabal test
159  
160  # All components
161  make test
162  ```
163  
164  ### Writing Tests
165  
166  - Write tests for new features
167  - Maintain or improve coverage
168  - Include edge cases
169  
170  ## Documentation
171  
172  - Update README.md for user-facing changes
173  - Update ARCHITECTURE.md for design changes
174  - Add inline comments for complex logic
175  - Keep examples up to date
176  
177  ## Release Process
178  
179  1. Version bump in relevant files
180  2. Update CHANGELOG.md
181  3. Create release tag
182  4. CI builds and publishes
183  
184  ## Getting Help
185  
186  - Open an issue for questions
187  - Check existing documentation
188  - Review closed issues
189  
190  ## Recognition
191  
192  Contributors are recognized in:
193  - Release notes
194  - CONTRIBUTORS file (coming soon)
195  
196  Thank you for contributing to ecological and economically conscious software development!