tla_visualiser/CONTRIBUTING.md

Contributing to TLA+ Visualiser

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers and help them learn
• Focus on constructive feedback
• Respect different viewpoints and experiences

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/tla_visualiser.git
   cd tla_visualiser
   

3. Set up development environment (see BUILDING.md)
4. Create a branch for your work:

   git checkout -b feature/my-new-feature
   

Development Workflow

1. Making Changes

• Keep changes focused and atomic
• Follow existing code style
• Add tests for new functionality
• Update documentation as needed

2. Code Style

C++

• Follow C++20 best practices
• Use meaningful variable names
• Prefer const where applicable
• Use smart pointers over raw pointers
• RAII for resource management

Example:

// Good
auto importer = std::make_unique<GitHubImporter>();
const auto url_info = importer->parseUrl(url);

// Avoid
GitHubImporter* importer = new GitHubImporter();
auto url_info = importer->parseUrl(url);
delete importer;

QML

• Use consistent indentation (4 spaces)
• Group properties logically
• Use property bindings where appropriate
• Add comments for complex logic

Example:

Rectangle {
    id: root
    
    // Size properties
    width: 200
    height: 100
    
    // Visual properties
    color: "#f0f0f0"
    border.color: "#cccccc"
    border.width: 1
    
    // Content
    Text {
        anchors.centerIn: parent
        text: "Hello"
    }
}

3. Commits

Write clear, descriptive commit messages:

Short summary (50 chars or less)

More detailed explanation if needed. Wrap at 72 characters.
Explain what changes were made and why.

- Bullet points are okay
- Use imperative mood: "Add feature" not "Added feature"

4. Testing

Always test your changes:

# Quick: Simulate full CI workflow locally
./simulate_workflow.sh

# Or manually:
# Build
cmake --build build --config Release

# Run tests
cd build
ctest --output-on-failure

# Run specific test
./tests/test_github_importer

Workflow Simulation Options:

./simulate_workflow.sh              # Full simulation
./simulate_workflow.sh --no-tests   # Skip tests (faster)
./simulate_workflow.sh --debug      # Debug build
./simulate_workflow.sh --no-lint    # Skip lint checks

The simulation script mirrors the gated tree workflow used in CI, ensuring your changes will pass before pushing.

Writing Tests

Add tests for new functionality:

#include <QtTest/QtTest>
#include "my_class.h"

class TestMyClass : public QObject
{
    Q_OBJECT

private slots:
    void testFeature();
};

void TestMyClass::testFeature()
{
    MyClass obj;
    QCOMPARE(obj.getValue(), 42);
}

QTEST_MAIN(TestMyClass)
#include "test_my_class.moc"

5. Documentation

Update documentation for:

• New features
• API changes
• Build requirements
• Usage instructions

Documentation locations:

• README.md: Overview and quick start
• docs/BUILDING.md: Build instructions
• docs/ARCHITECTURE.md: Architecture details
• Code comments: Public API and complex logic

Pull Request Process

1. Before Submitting

• Code builds successfully
• All tests pass
• New tests added for new features
• Documentation updated
• Code follows style guidelines
• Commit messages are clear
• Workflow simulation passes: ./simulate_workflow.sh

CI Gated Tree Workflow: Your PR must pass through the gated tree workflow:

1. Lint checks - Code quality and formatting
2. Build jobs - All platforms (Linux, macOS, Windows)
3. Test jobs - All tests must pass
4. Gate check - Final verification that all jobs succeeded

The gate will block merging if any check fails.

2. Submitting PR

1. Push your branch to your fork:

   git push origin feature/my-new-feature
   

2. Open a pull request on GitHub

3. Fill in the PR template:

   • Describe the changes
   • Reference related issues
   • List testing performed
   • Add screenshots for UI changes

3. Review Process

• Maintainers will review your PR
• Address feedback by pushing new commits
• Once approved, maintainer will merge

4. After Merge

• Delete your feature branch
• Pull latest changes:

  git checkout main
  git pull upstream main
  

Types of Contributions

Bug Fixes

1. Check if issue already exists
2. If not, create an issue describing the bug
3. Reference the issue in your PR

New Features

1. Discuss in an issue first (for large features)
2. Implement the feature
3. Add tests and documentation
4. Submit PR

Documentation

Documentation improvements are always welcome:

• Fix typos
• Clarify instructions
• Add examples
• Improve organization

Testing

Help improve test coverage:

• Add missing tests
• Improve existing tests
• Add integration tests

Project Structure

tla_visualiser/
├── CMakeLists.txt          # Build configuration
├── conanfile.txt           # Dependencies
├── src/                    # C++ implementation
├── include/                # Public headers
├── qml/                    # QML UI files
├── tests/                  # Unit tests
├── examples/               # Example TLA+ specs
├── docs/                   # Documentation
└── .github/workflows/      # CI/CD

Development Tips

Building in Debug Mode

cmake -B build-debug -G Ninja \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_TOOLCHAIN_FILE=build-debug/conan_toolchain.cmake
cmake --build build-debug

Running with Debugging

# GDB
gdb ./build-debug/tla_visualiser

# LLDB
lldb ./build-debug/tla_visualiser

Qt Creator

Open CMakeLists.txt in Qt Creator for integrated development:

• Syntax highlighting
• Code completion
• Visual debugging
• QML preview

Verbose Build

cmake --build build --config Release --verbose

CMake Reconfigure

cmake --build build --target rebuild_cache

Getting Help

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions or discuss ideas
• Documentation: Check docs/ directory

Recognition

Contributors will be:

• Listed in release notes
• Credited in documentation
• Acknowledged in the project

Thank you for contributing to TLA+ Visualiser!