Contributing to the Zen Programming Language

Thank you for your interest in contributing to the Zen Programming Language! This document outlines the guidelines and principles for making contributions.

Philosophy and Guiding Principles

The Zen language is founded on a unique philosophy of "No keywords. Pure expression. Allocator-driven concurrency." All contributions must align with the core design principles:

• No Keywords: Strictly adhere to the zero-keyword design.
• Pattern Matching with ?: Utilize the ? operator for all conditional logic.
• UFC (Uniform Function Call): Embrace the convention that any function can be called as a method.
• Allocator-Driven Concurrency: Ensure that concurrency behavior is determined by allocators, avoiding explicit async/await keywords or function coloring.
• Explicit Pointer Types: Use Ptr<>, MutPtr<>, RawPtr<> for all pointer manipulations.
• No Null/Nil: Always use Option<T> for potentially absent values.
• .raise() for Error Propagation: Propagate errors explicitly using .raise() instead of exceptions.
• Compile-time Metaprogramming: Leverage the full AST access for powerful compile-time transformations.

The absolute source of truth for the language is LANGUAGE_SPEC.zen. All changes to the compiler or standard library must reflect and conform to this specification. If you believe the specification needs alteration, please initiate a discussion before implementing changes.

For a broader overview of the language, please refer to the [Zen Programming Language Overview].

Project Status

The Zen language has achieved significant progress, with core features working well and a strong test suite. The project is actively moving towards a complete implementation of its zero-keywords design. For the latest development status, including working, partially working, and not yet implemented features, please see STATUS.md.

How to Contribute

1. Understanding the Specification

Before writing any code, thoroughly read and understand LANGUAGE_SPEC.zen. This is paramount to ensure your contributions align with the language's fundamental design.

2. Setting up Your Development Environment

The Zen compiler is written in Rust.

To get started, clone the repository and build the compiler:

3. Running Examples and Tests

To familiarize yourself with the language and verify your setup, run the showcase example and the test suite:

The test suite is critical; all tests must pass for any pull request to be considered.

4. Areas of Contribution

We welcome contributions in the following areas:

• Implementing Missing Features: Focus on items listed under "Not Yet Implemented" or "Partially Working" in STATUS.md, ensuring adherence to LANGUAGE_SPEC.zen.
  • Metaprogramming: Expanding compile-time AST manipulation.
  • Full Pointer Types: Completing Ptr<T>, MutPtr<T>, RawPtr<T> support.
  • Concurrency Primitives: Implementing the actor model and channels.
  • Module System: Finalizing module.exports and module.import functionality.
  • Self-Hosted Build System: Progressing towards build.zen for project compilation.
  • Full FFI: Enhancing inline.c() and FFI capabilities.
• Standard Library Development: Expanding the standard library modules (e.g., stdlib/io.zen, stdlib/collections.zen) with new functions and types, always adhering to the zero-keyword principle.
• Bug Fixes: Identifying and resolving issues in the compiler, runtime, or standard library.
• Performance Optimizations: Improving the speed and efficiency of the compiler or generated code.
• Documentation: Enhancing explanations, examples, and language guides.

5. Reporting Issues

If you find a bug, have a feature request, or suggest an improvement:

1. Check existing issues: Before opening a new issue, please check if a similar one already exists in the GitHub issue tracker.
2. Open a new issue: If not, open a new issue.
   • Bugs: Provide a clear title, a detailed description of the problem, steps to reproduce it, expected behavior, and actual behavior. Include any relevant error messages or code snippets.
   • Feature Requests/Suggestions: Describe the proposed feature, its motivation, and how it aligns with Zen's design principles.

6. Submitting Code

1. Fork the repository: Start by forking the lantos1618/zenlang repository on GitHub.
2. Create a new branch: For each contribution, create a new branch from main with a descriptive name (e.g., feature/add-actors, bugfix/fix-type-inference).
3. Implement your changes: Write your code, ensuring it is clean, well-structured, and follows the Zen design principles.
4. Write tests: For any new features or bug fixes, write comprehensive unit and/or integration tests to cover your changes. Ensure these tests are added to the tests/ directory and pass reliably.
5. Run tests: Before submitting, run the full test suite (python3 scripts/run_tests.py) to confirm all tests pass.
6. Update documentation: If your changes affect the language, its usage, or a standard library module, update the relevant documentation (README.md, LANGUAGE_SPEC.zen, STATUS.md, or docs/ files if they existed).
7. Commit your changes: Write clear, concise commit messages that explain the purpose of your changes.
8. Push your branch: Push your new branch to your forked repository.
9. Open a Pull Request:
   • Target the main branch of the lantos1618/zenlang repository.
   • Provide a clear and detailed description of your changes, referencing any related issues.
   • Explain how your contribution adheres to the LANGUAGE_SPEC.zen.
   • Confirm that all tests pass.

7. Coding Style

• Consistency: Maintain consistency with the existing codebase's style.
• Readability: Write readable code with clear variable names and logical flow.
• Zen Philosophy: Ensure your code reflects the minimalist, keyword-less philosophy.

8. Review Process

All pull requests will be reviewed by the project maintainers. Be open to feedback and willing to iterate on your changes. The goal is to ensure high-quality contributions that align with the project's vision.

License

By contributing to the Zen Programming Language, you agree that your contributions will be licensed under the MIT License, as specified in the repository's LICENSE file.