Contributing to mackan.eu

Thank you for your interest in contributing! This document covers the JSON Toolbox and other developer utilities.

---

Code of Conduct

Be respectful, constructive, and inclusive. We welcome contributors of all skill levels.

---

How to Contribute

Reporting Bugs

1. Search existing issues to avoid duplicates
2. Use the bug report template
3. Include:
   • Steps to reproduce
   • Expected vs actual behavior
   • Browser/Node.js version
   • Sample input (if applicable)

Suggesting Features

1. Search existing issues
2. Use the feature request template
3. Include:
   • Use case description
   • Proposed solution
   • Alternative approaches considered

Submitting Code

1. Fork the repository
2. Create a feature branch: feature/your-feature-name
3. Make changes following code style guide
4. Test your changes
5. Submit a pull request

---

Development Setup

Prerequisites

• PHP 7.4+ (for local development server)
• Node.js 16+ (for CLI development)
• Git

Local Development

# Clone repository
git clone https://github.com/retea-se/mackan.eu.git
cd mackan.eu

# Start local server
php -S localhost:8000

# Open in browser
open http://localhost:8000/tools/json/

CLI Development

cd tools/json/cli

# Run tests
node test/smoke.js
node test/parity.js

# Build bundle
node build/bundle.js

---

Code Style

JavaScript

• ES2020+ syntax
• No external dependencies in core modules
• Pure functions where possible
• JSDoc comments for public APIs

/**
 * Parse CSV string to array of objects.
 * @param {string} input - CSV string
 * @param {Object} params - Parser options
 * @param {boolean} params.header - First row is header
 * @returns {Array} Parsed data
 */
function parseCsv(input, params = {}) {
  // ...
}

PHP

• PSR-12 style
• Minimal dependencies
• Security-first (no user data transmitted)

CSS

• Designsystem: Scanline + Monospace + Flat Grid. Se docs/DESIGN_SYSTEM_SCANLINE.md i huvudrepot.
• Tre byggstenar: scanline-textur (CRT-linjer), monospace-etiketter (JetBrains Mono), flat grid (whitespace-separation)
• Accent: #5ba3d9 (en enda farg). Inga border-left-accent-kort.
• Design tokens in :root
• BEM-like naming
• Mobile-first responsive

Commit Messages

Follow Conventional Commits:

type(scope): description

feat(json-toolbox): add NDJSON support
fix(csv): handle empty rows correctly
docs(cli): update installation instructions
chore(build): update bundle script

Types: feat, fix, docs, style, refactor, test, chore

---

Project Structure

tools/json/
├── index.php          # Main page
├── script.js          # Core orchestration
├── style.css          # Styles
├── modules/           # Feature modules
│   ├── csv.js
│   ├── format.js
│   └── ...
├── operators/         # Pipeline operators
│   ├── index.js
│   └── ...
├── cli/               # CLI implementation
│   ├── bin/
│   ├── lib/
│   ├── dist/
│   └── test/
└── vendor/            # Self-hosted dependencies

---

Adding an Operator

1. Create operator in operators/<namespace>.js
2. Register in operators/index.js
3. Add corresponding CLI operator in cli/lib/operators/
4. Add tests in cli/test/
5. Document in OPERATORS.md

Operator Requirements

• Pure function (no side effects)
• Deterministic output
• Defined input/output types
• Parameter schema with defaults
• Error handling

// operators/example.js
export const myOperator = {
  name: 'example.myop',
  inputType: 'string',
  outputType: 'array',
  params: {
    option: { type: 'boolean', default: false }
  },
  run(input, params) {
    // Transform input
    return result;
  }
};

---

Testing

Browser Testing

1. Manual testing in Chrome/Firefox
2. Check console for errors
3. Test both light/dark themes
4. Test Swedish/English

CLI Testing

cd tools/json/cli

# Smoke tests (all operators)
node test/smoke.js

# Parity tests (browser-CLI match)
node test/parity.js

# Golden tests (expected output)
node test/golden.js

Adding Tests

Add test cases to cli/test/data/ and update test files.

---

Pull Request Process

1. Branch naming: feature/, fix/, docs/
2. PR title: Follow conventional commits format
3. Description: Include context and testing done
4. Review: Wait for maintainer review
5. Merge: Squash and merge preferred

PR Checklist

• Code follows style guide
• Tests pass
• Documentation updated
• No console errors
• Works in both browser and CLI (if applicable)

---

Issue Labels

Label	Description
bug	Something isn't working
enhancement	New feature or improvement
cli	CLI-specific
docs	Documentation
pipeline	Pipeline engine
interop	Format conversion
good-first-issue	Good for newcomers

---

Release Process

Releases are managed by maintainers:

1. Update version in files
2. Update CHANGELOG
3. Create release branch
4. PR to main
5. Tag release
6. Create GitHub release

---

Questions?

• Open an issue with question label
• Check existing documentation
• Review closed issues for similar questions

---

License

By contributing, you agree that your contributions will be licensed under the MIT License.