CONTRIBUTING.md

Contributing to Matrikkel Java Integration

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

Getting Started

1. Fork the repository
2. Clone your fork

   git clone https://github.com/your-username/matrikkel-java.git
   cd matrikkel-java

3. Set up development environment
   • Install Java 17+
   • Install Maven 3.9+
   • Set up PostgreSQL 15+
   • Copy .env.example to .env and configure

Development Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Branch naming conventions:

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation changes
• refactor/ - Code refactoring
• test/ - Test additions or changes

2. Make Your Changes

Follow these guidelines:

Code Style

• Follow standard Java conventions
• Use Lombok annotations to reduce boilerplate
• Add Javadoc for public methods
• Keep methods focused and small
• Use meaningful variable names

Testing

• Write unit tests for new functionality
• Ensure all tests pass: mvn test
• Add integration tests for complex features
• Aim for >80% code coverage

Documentation

• Update README.md if needed
• Add comments for complex logic
• Update CHANGELOG.md with your changes
• Keep .copilot-context.md updated with new patterns

3. Commit Your Changes

Use clear, descriptive commit messages:

git commit -m "feat: Add support for Adresse import"
git commit -m "fix: Handle null snapshotVersion in MatrikkelContext"
git commit -m "docs: Update README with new configuration options"

Commit message format:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Test additions or changes
• chore: - Maintenance tasks

4. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a Pull Request on GitHub with:

• Clear title describing the change
• Detailed description of what and why
• Reference any related issues
• Screenshots if applicable

Code Standards

Java Code

// Good example
@Service
@RequiredArgsConstructor
@Slf4j
public class MatrikkelenhetImportService {
    
    private final NedlastningClientWrapper nedlastningClient;
    private final MatrikkelenhetRepository repository;
    
    /**
     * Import matrikkelenheter for a specific kommune.
     * 
     * @param kommunenummer The kommune number (e.g., "4601")
     * @return Number of imported matrikkelenheter
     * @throws MatrikkelApiException if API call fails
     */
    @Transactional
    public int importMatrikkelenheterForKommune(String kommunenummer) {
        log.info("Starting import for kommune {}", kommunenummer);
        // Implementation...
    }
}

Configuration

• Use application.yml for configuration
• Never commit credentials
• Document all configuration options
• Use type-safe @ConfigurationProperties

Database

• Always use Flyway migrations
• Never use ddl-auto: create in production
• Add proper indexes for queries
• Document schema changes in migration files

SOAP Clients

• Create wrapper classes for generated clients
• Handle pagination properly
• Add retry logic for transient failures
• Log all API calls at DEBUG level

Testing Guidelines

Unit Tests

@ExtendWith(MockitoExtension.class)
class MatrikkelenhetImportServiceTest {
    
    @Mock
    private NedlastningClientWrapper nedlastningClient;
    
    @Mock
    private MatrikkelenhetRepository repository;
    
    @InjectMocks
    private MatrikkelenhetImportService service;
    
    @Test
    void shouldImportMatrikkelenheter() {
        // Given
        String kommunenummer = "4601";
        // ... setup mocks
        
        // When
        int result = service.importMatrikkelenheterForKommune(kommunenummer);
        
        // Then
        assertEquals(expectedCount, result);
        verify(repository).saveAll(anyList());
    }
}

Integration Tests

@SpringBootTest
@Testcontainers
class MatrikkelenhetRepositoryIntegrationTest {
    
    @Container
    static PostgreSQLContainer<?> postgres = 
        new PostgreSQLContainer<>("postgres:15-alpine");
    
    @Test
    void shouldSaveAndRetrieveMatrikkelenhet() {
        // Test implementation
    }
}

Pull Request Checklist

Before submitting a PR, ensure:

• Code follows project conventions
• All tests pass (mvn test)
• New code has test coverage
• Documentation is updated
• CHANGELOG.md is updated
• No credentials or sensitive data committed
• Commit messages are clear and descriptive
• Branch is up to date with main
• No merge conflicts

Reporting Issues

When reporting issues, include:

1. Description - Clear description of the problem
2. Steps to Reproduce - Detailed steps to reproduce the issue
3. Expected Behavior - What you expected to happen
4. Actual Behavior - What actually happened
5. Environment - Java version, OS, database version
6. Logs - Relevant log output (sanitize any credentials!)
7. Screenshots - If applicable

Questions?

• Check the JAVA_PROJECT_SETUP_GUIDE.md
• Review .copilot-context.md
• Read the README.md
• Open a discussion on GitHub

License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Thank you for contributing! 🎉