diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b296993 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,635 @@ +# Contributing to JWT Parser + +**[🇷🇺 Русский](#участие-в-разработке-ru)** | **🇺🇸 English** + +--- + +## 🤝 Welcome Contributors! + +Thank you for your interest in contributing to JWT Parser! This document provides guidelines and instructions for contributing. + +## 📋 Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Setup](#development-setup) +- [Testing](#testing) +- [Pull Request Process](#pull-request-process) +- [Coding Standards](#coding-standards) + +--- + +## 📜 Code of Conduct + +This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. + +**Be respectful, inclusive, and constructive.** + +--- + +## 🎯 How Can I Contribute? + +### Reporting Bugs + +Before creating bug reports, please check existing issues to avoid duplicates. + +**Bug Report Template:** +```markdown +**Description:** Brief description of the bug + +**To Reproduce:** +1. Step 1 +2. Step 2 +3. ... + +**Expected Behavior:** What you expected to happen + +**Actual Behavior:** What actually happened + +**Environment:** +- OS: [e.g., Alpine Linux, Astra Linux SE] +- Bash Version: [e.g., 5.1.16] +- Go Version (if applicable): [e.g., 1.21.5] +- Available Tools: [e.g., jq: yes, openssl: yes] + +**Token Structure (NO SECRETS):** +```json +{ + "header": {...}, + "payload": {...} +} +``` +``` + +### Suggesting Enhancements + +Enhancement suggestions are welcome! Please: +- Use a clear and descriptive title +- Provide detailed description of the enhancement +- Explain why this would be useful +- Provide examples if applicable + +### Pull Requests + +We actively welcome your pull requests! + +--- + +## 🛠️ Development Setup + +### Prerequisites + +- **Bash:** 4.0 or higher +- **Go:** 1.21 or higher (for Go components) +- **Git:** Latest version +- **Optional:** jq, openssl (for testing) + +### Setup Instructions + +```bash +# Clone your fork +git clone https://github.com/YOUR_USERNAME/jwt-parser.git +cd jwt-parser + +# Add upstream remote +git remote add upstream https://github.com/AlexGromer/jwt-parser.git + +# Create feature branch +git checkout -b feature/your-feature-name + +# Install Go dependencies +make deps + +# Run tests to verify setup +make test +``` + +--- + +## 🧪 Testing + +**All contributions must include tests.** + +### Running Tests + +```bash +# Run all tests +make test + +# Run specific test suite +bash tests/unit/test_bash_parser.sh +bash tests/security/test_security.sh +bash tests/compatibility/test_compatibility.sh +bash tests/integration/test_integration.sh +go test -v + +# Check test coverage (Go) +go test -coverprofile=coverage.txt +go tool cover -html=coverage.txt +``` + +### Writing Tests + +#### Bash Tests + +Add tests to appropriate file in `tests/`: +- `tests/unit/` - Unit tests for bash parser +- `tests/security/` - Security-related tests +- `tests/compatibility/` - Compatibility tests +- `tests/integration/` - Integration tests + +Example: +```bash +test_your_feature() { + local token="eyJhbGci..." + local output=$("$PARSER" "$token" 2>&1) + + assert_contains "$output" "expected_text" "Test description" +} +test_your_feature +``` + +#### Go Tests + +Add tests to `jwt-parser_test.go`: + +```go +func TestYourFeature(t *testing.T) { + parser := NewJWTParser() + result, err := parser.Parse(tokenString) + + if err != nil { + t.Fatalf("Parse failed: %v", err) + } + + if result.Subject != "expected" { + t.Errorf("Expected 'expected', got '%s'", result.Subject) + } +} +``` + +--- + +## 🔄 Pull Request Process + +1. **Update Documentation** + - Update README if adding features + - Add/update examples if needed + - Update CHANGELOG.md (if exists) + +2. **Ensure Tests Pass** + ```bash + make test + ``` + All 131 tests must pass! + +3. **Follow Commit Message Format** + ``` + : + + + +