mirror of
https://github.com/th30d4y/ExecuTrace.git
synced 2026-05-26 19:36:32 +00:00
Merge pull request #2 from Stalin-143/copilot/update-contributing-md
docs: populate CONTRIBUTING.md with full contribution guide
This commit is contained in:
Stalin
+196
@@ -1 +1,197 @@
|
||||
# Contributing to ExecuTrace
|
||||
|
||||
Thank you for your interest in contributing to **ExecuTrace**! Whether you're fixing a bug, proposing a new feature, improving the docs, or just sharing feedback, every contribution is welcome.
|
||||
|
||||
Please take a moment to read this guide before you start.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Ways to Contribute](#ways-to-contribute)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Running Tests](#running-tests)
|
||||
- [Coding Standards](#coding-standards)
|
||||
- [Commit Message Conventions](#commit-message-conventions)
|
||||
- [Pull Request Process](#pull-request-process)
|
||||
- [Reporting Bugs](#reporting-bugs)
|
||||
- [Suggesting Features](#suggesting-features)
|
||||
- [Documentation](#documentation)
|
||||
- [Security Vulnerabilities](#security-vulnerabilities)
|
||||
- [Hall of Fame](#hall-of-fame)
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating you agree to uphold its standards. Please report unacceptable behaviour to **w4nn4d133@gmail.com**.
|
||||
|
||||
---
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
| Type | How |
|
||||
|---|---|
|
||||
| 🐛 Bug fix | Open an issue first, then submit a PR |
|
||||
| ✨ New feature | Open a feature-request issue to discuss scope |
|
||||
| 📖 Documentation | Edit Markdown files or the `website/` source |
|
||||
| 🧪 Tests | Add or improve tests in `test_comprehensive.py` |
|
||||
| 🔐 Security | See [Security Vulnerabilities](#security-vulnerabilities) |
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.9 or higher
|
||||
- `git`
|
||||
|
||||
### Fork & clone
|
||||
|
||||
```bash
|
||||
git clone https://github.com/<your-username>/ExecuTrace.git
|
||||
cd ExecuTrace
|
||||
```
|
||||
|
||||
### Create a virtual environment
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
```
|
||||
|
||||
### Install in editable mode
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Verify the installation
|
||||
|
||||
```bash
|
||||
exectrace --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ExecuTrace/
|
||||
├── exectrace/ # Core library
|
||||
│ ├── cli.py # Command-line interface
|
||||
│ ├── core/ # Replayer and workflow models
|
||||
│ ├── recorder/ # Session recording logic
|
||||
│ ├── storage/ # JSON & XML storage backends
|
||||
│ └── utils/ # Logging, interactive prompts
|
||||
├── website/ # Documentation website (GitHub Pages)
|
||||
│ ├── index.html
|
||||
│ └── data/
|
||||
│ ├── contributors.json
|
||||
│ └── security_hof.json
|
||||
├── test_comprehensive.py # Test suite
|
||||
├── pyproject.toml # Build & packaging configuration
|
||||
├── CONTRIBUTING.md # This file
|
||||
├── CODE_OF_CONDUCT.md
|
||||
├── SECURITY.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
python test_comprehensive.py
|
||||
```
|
||||
|
||||
All tests must pass before submitting a pull request. If you add new functionality, please add corresponding tests.
|
||||
|
||||
---
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- Follow [PEP 8](https://peps.python.org/pep-0008/) for Python code style.
|
||||
- Use type annotations for all public functions and methods (Python 3.9+ syntax).
|
||||
- Keep functions focused and small — prefer multiple simple functions over one large one.
|
||||
- Use the `get_logger` utility from `exectrace.utils.logger` for logging rather than `print` in library code.
|
||||
- Do not introduce new dependencies without prior discussion in an issue.
|
||||
|
||||
---
|
||||
|
||||
## Commit Message Conventions
|
||||
|
||||
Use short, imperative messages in the present tense:
|
||||
|
||||
```
|
||||
fix: handle missing workflow file gracefully
|
||||
feat: add --timeout flag to replay command
|
||||
docs: add contribution guide
|
||||
test: cover XML storage edge cases
|
||||
refactor: extract prompt helpers into utils module
|
||||
```
|
||||
|
||||
Prefix categories: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`.
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. **Branch** off `main` with a descriptive name:
|
||||
```bash
|
||||
git checkout -b fix/replay-dry-run-output
|
||||
```
|
||||
2. **Make your changes** in small, focused commits.
|
||||
3. **Run the tests** and confirm everything passes.
|
||||
4. **Push** your branch and open a Pull Request against `main`.
|
||||
5. Fill in the PR description explaining *what* changed and *why*.
|
||||
6. A maintainer will review your PR. Please respond to feedback promptly.
|
||||
7. Once approved, the PR will be merged by a maintainer.
|
||||
|
||||
> For large changes, open an issue for discussion **before** writing code to avoid wasted effort.
|
||||
|
||||
---
|
||||
|
||||
## Reporting Bugs
|
||||
|
||||
1. Search [existing issues](https://github.com/Stalin-143/ExecuTrace/issues) to check whether the bug has already been reported.
|
||||
2. If not, open a new issue and include:
|
||||
- ExecuTrace version (`pip show exectrace-workflow`)
|
||||
- Python version and OS
|
||||
- Steps to reproduce
|
||||
- Expected vs. actual behaviour
|
||||
- Relevant error output or logs
|
||||
|
||||
---
|
||||
|
||||
## Suggesting Features
|
||||
|
||||
1. Search existing issues for similar requests.
|
||||
2. Open an issue with the label **enhancement** and describe:
|
||||
- The problem you're trying to solve
|
||||
- Your proposed solution
|
||||
- Any alternatives you've considered
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
The project documentation website lives in `website/`. It is a static HTML site deployed via GitHub Pages.
|
||||
|
||||
- To add yourself to the contributors list, update `website/data/contributors.json`.
|
||||
- For content changes, edit `website/index.html` and open a PR.
|
||||
|
||||
---
|
||||
|
||||
## Security Vulnerabilities
|
||||
|
||||
Please **do not** open a public issue for security bugs. Follow the responsible-disclosure process described in [SECURITY.md](SECURITY.md).
|
||||
|
||||
---
|
||||
|
||||
## Hall of Fame
|
||||
|
||||
Contributors and responsible security reporters are credited on the project website. Thank you for helping make ExecuTrace better!
|
||||
|
||||
Reference in New Issue
Block a user