CONTRIBUTING.md

Contributing to PerlOnJava

We welcome contributions! This guide will help you get started.

PerlOnJava is actively developed in its compatibility and performance phase. The broad language implementation is in place, so the highest-impact work now closes remaining Perl behavior gaps, expands CPAN compatibility, and improves CPU and memory performance.

Ways to Contribute

• Report bugs - Open issues on GitHub
• Fix bugs - Submit pull requests
• Add features - Implement missing Perl features
• Improve docs - Fix typos, add examples, clarify explanations
• Port modules - Help port CPAN modules to PerlOnJava
• Write tests - Add test coverage
• Share compatibility results - Report reproducible jcpan -t failures
• Measure performance - Contribute repeatable CPU, memory, and startup benchmarks

Quick Start for Contributors

1. Set Up Development Environment

# Clone repository
git clone https://github.com/fglock/PerlOnJava.git
cd PerlOnJava

# Build and run tests
make        # Build + run all unit tests

# Run comprehensive tests
make test-all

2. Development Workflow

Before making changes:

1. Create a feature branch: git checkout -b feature-name
2. Never push directly to master — always use feature branches and PRs
3. Read the Architecture Guide
4. Check Project Status and Roadmap for current priorities

While coding:

1. Follow existing code style
2. Run make frequently to ensure tests pass
3. Add tests for new features in src/test/resources/unit/

Before committing:

1. Ensure make passes (all unit tests)
2. Write clear commit messages

3. Submit Pull Request

1. Push your branch: git push origin feature-name
2. Open a PR on GitHub
3. Describe what your PR does and why
4. Link related issues

The #1 priority is keeping make working. All unit tests must pass.

Code Organization

Source Code Structure

src/main/java/org/perlonjava/
├── astnode/         # AST node representations
├── parser/          # Parser implementation
├── lexer/           # Tokenization
├── codegen/         # Bytecode generation and class creation
├── astvisitor/      # AST traversal (EmitterVisitor, PrinterVisitor)
├── runtime/         # Runtime implementations (RuntimeScalar, RuntimeArray, etc.)
├── operators/       # Operator implementations
├── regex/           # Regex engine integration
├── perlmodule/      # Java implementations of Perl modules
└── scriptengine/    # JSR 223 scripting API

src/main/perl/lib/   # Perl module implementations
src/test/resources/  # Test files

Key Components

• Lexer (lexer/Lexer.java) - Tokenizes Perl source
• Parser (parser/Parser.java) - Builds AST from tokens
• EmitterVisitor (astvisitor/) - Traverses AST and coordinates bytecode generation
• Emit classes (codegen/) - Generate JVM bytecode using ASM library
• Runtime (runtime/) - RuntimeScalar, RuntimeArray, RuntimeHash, RuntimeCode
• Operators (operators/) - Perl operator implementations

Test Organization

src/test/resources/
└── unit/            # Fast unit tests (run in seconds)

perl5_t/ (at project root)
├── t/               # Perl 5 core test suite
└── [Module]/        # Perl 5 module tests

Development Guidelines

Building and Testing

# Build + run all unit tests (default)
make

# Run all tests including Perl 5 core tests
make test-all

# Run single test
./jperl path/to/test.t

Adding Tests

1. Create .t file in src/test/resources/unit/
2. Use TAP format (Test::More compatible)
3. Test should complete in < 1 second
4. Run with ./jperl path/to/test.t

Example test:

print "1..3\n";  # Plan
print "ok 1 - basic test\n";
my $x = 1 + 1;
print $x == 2 ? "ok 2\n" : "not ok 2\n";
print "ok 3 - done\n";

Debugging

# Show debug information
./jperl --debug -E 'code'

# Check syntax only
./jperl -c script.pl

# Show disassembled bytecode
./jperl --disassemble script.pl

# Run lexer only
./jperl --tokenize -E 'code'

# Run parser only
./jperl --parse -E 'code'

Documentation

User Documentation

User-facing documentation is in docs/:

• getting-started/ - Installation, quick start, Docker
• guides/ - How-to guides (database, Java integration, modules)
• reference/ - Technical reference (features, testing, architecture)
• about/ - Project information (why, roadmap, support)

Developer Documentation

Developer documentation is in dev/:

• architecture/ - Internal architecture docs
• implementation/ - Implementation notes (regex, tie, overload)
• maintenance/ - Maintenance procedures

See also AGENTS.md for detailed testing commands, unimplemented features, environment variables, and git workflow rules.

Feature Development

Before Adding a Feature

1. Check if it's in Feature Matrix
2. Review Roadmap
3. Open an issue to discuss the approach
4. Read relevant design docs in dev/

High-Risk Areas

When modifying these, test extensively:

• String parsing (parser/StringDoubleQuoted.java)
• Lexer (lexer/Lexer.java)
• Unicode handling - Surrogate pairs, identifier parsing
• Control flow - die/eval, loop control
• Bytecode generation (codegen/, astvisitor/EmitterVisitor.java)

Adding Operators

1. Implement in operators/ package
2. Add parser support in parser/
3. Add tests in src/test/resources/unit/
4. Update Feature Matrix

Porting Modules

See Module Porting Guide for:

• How to port pure-Perl modules
• Implementing XS modules in Java
• Using XSLoader mechanism

Community

• GitHub Issues - Bug reports and feature requests
• Pull Requests - Code contributions
• Discussions - Questions and design discussions

AI-Assisted Contributions

PerlOnJava accepts AI-assisted contributions with proper attribution. See AI_POLICY.md for our full policy on commit attribution, human responsibility, and how our approach compares to other open-source projects.

Code of Conduct

• Be respectful and constructive
• Focus on technical merit
• Help newcomers
• Keep discussions on-topic

Getting Help

• Read the Architecture Guide
• Check existing Issues
• Ask in Discussions
• See Support for more resources

License

By contributing, you agree that your contributions will be licensed under the same terms as Perl 5 (Artistic License or GPL v1+).