Jython Developer’s Guide

Note

These instructions are a modified version of the CPython devguide

This guide is a comprehensive resource for contributing to Jython – for both new and experienced contributors. It is maintained by the same community that maintains Jython. We welcome your contributions to Jython!

Quick Start

Here are the basic steps needed to get set up and contribute a patch:

1. Get the source code:

   hg clone http://hg.python.org/jython
   

2. Build Jython:

   ant
   

3. Run the tests:

   ant regrtest
   

4. Make the patch.

5. Submit it to the issue tracker.

Quick Links

Here are some links that you probably will reference frequently while contributing to Jython.

• Issue tracker
• Jython Developer FAQ
• PEPs (Python Enhancement Proposals)

Contributing

We encourage everyone to contribute to Jython and that’s why we have put up this developer’s guide. If you still have questions after reviewing the material in this guide, then the Python Mentors group is available to help guide new contributors through the process. The Developer FAQ is another useful source of information.

Guide for contributing to Jython:

• Getting Started

• Where to Get Help

• Lifecycle of a Patch

• Running & Writing Tests

• Beginner tasks to become familiar with the development process

  • Helping with Documentation
  • Note for Jython

• Advanced tasks for once you are comfortable

  • Silence Warnings From the Test Suite
  • Fixing issues found by the buildbots
  • Fixing “easy” Issues (and Beyond)

• Using the Issue Tracker and Helping Triage Issues

  • Triaging an Issue

• Following Jython’s Development

• How to Become a Core Developer

  • Committing and Pushing Changes
  • Development Cycle
  • Continuous Integration
  • Coverity Scan

It is recommended that the above documents be read in the order listed. You can stop where you feel comfortable and begin contributing immediately without reading and understanding these documents all at once. If you do choose to skip around within the documentation, be aware that it is written assuming preceding documentation has been read so you may find it necessary to backtrack to fill in missing concepts and terminology.

Other Interpreter Implementations

This guide is specifically for contributing to Jython: A Python interpreter focused on good integration with the Java Virtual Machine (JVM) environment.

There are other Python implementations, each with a different focus. Like CPython, they always have more things they would like to do than they have developers to work on them. Some major example that may be of interest are:

• CPython: The Python reference interpreter, also called simply “Python”
• PyPy: A Python interpreter focused on high speed (JIT-compiled) operation on major platforms
• IronPython: A Python interpreter focused on good integration with the Common Language Runtime (CLR) provided by .NET and Mono
• Stackless: A Python interpreter focused on providing lightweight microthreads while remaining largely compatible with CPython specific extension modules

Key Resources

• Coding style guides

  • PEP 8 (Style Guide for Python Code)
  • Oracle’s Java guidelines #TODO need link

• Issue tracker

  • Meta tracker (issue tracker for the issue tracker)
  • Experts Index
  • Firefox search engine plug-in

• Buildbot status

• Source code

  • Browse online

• PEPs (Python Enhancement Proposals)

• Jython Developer FAQ

• Developer Log

Additional Resources

• Anyone can clone the sources for this guide. See Helping with the Developer’s Guide.

• Help with ...

  • Changing CPython’s Grammar
  • Design of CPython’s Compiler

• Tool support

  • Emacs support
  • Various tools with configuration files as found in the Misc directory

• python.org maintenance

• Search this guide

Full Table of Contents

• 1. Getting Started
  • 1.1. Getting Set Up
    • 1.1.1. Version Control Setup
    • 1.1.2. Getting the Source Code
    • 1.1.3. Compiling
      • 1.1.3.1. Build dependencies
  • 1.2. Editors and Tools
  • 1.3. Directory Structure
• 2. Where to Get Help
  • 2.1. Ask #jython
  • 2.2. Core Mentorship
  • 2.3. Mailing Lists
  • 2.4. File a Bug
• 3. Lifecycle of a Patch
  • 3.1. Creating
    • 3.1.1. Tool Usage
    • 3.1.2. Preparation
    • 3.1.3. Generation
  • 3.2. Licensing
  • 3.3. Submitting
  • 3.4. Reviewing
  • 3.5. Committing/Rejecting
  • 3.6. Crediting
• 4. Running & Writing Tests
  • 4.1. Running
  • 4.2. Writing
• 5. Note for Jython
• 6. Increase Test Coverage
  • 6.1. Common Gotchas
  • 6.2. Measuring Coverage
    • 6.2.1. Using coverage.py
      • 6.2.1.1. Branch Coverage
      • 6.2.1.2. Coverage Results For Modules Imported Early On
    • 6.2.2. Using test.regrtest
  • 6.3. Filing the Issue
  • 6.4. Measuring coverage of Java code
• 7. Helping with Documentation
  • 7.1. Helping with issues filed on the issue tracker
  • 7.2. Proofreading
  • 7.3. Helping with the Developer’s Guide
• 8. Documenting Jython
  • 8.1. Introduction
  • 8.2. Style guide
    • 8.2.1. Use of whitespace
    • 8.2.2. Footnotes
    • 8.2.3. Capitalization
    • 8.2.4. Affirmative Tone
    • 8.2.5. Economy of Expression
    • 8.2.6. Security Considerations (and Other Concerns)
    • 8.2.7. Code Examples
    • 8.2.8. Code Equivalents
    • 8.2.9. Audience
  • 8.3. reStructuredText Primer
    • 8.3.1. Paragraphs
    • 8.3.2. Inline markup
    • 8.3.3. Lists and Quotes
    • 8.3.4. Source Code
    • 8.3.5. Hyperlinks
      • 8.3.5.1. External links
      • 8.3.5.2. Internal links
    • 8.3.6. Sections
    • 8.3.7. Explicit Markup
    • 8.3.8. Directives
    • 8.3.9. Footnotes
    • 8.3.10. Comments
    • 8.3.11. Source encoding
    • 8.3.12. Gotchas
  • 8.4. Additional Markup Constructs
    • 8.4.1. Meta-information markup
    • 8.4.2. Module-specific markup
    • 8.4.3. Information units
    • 8.4.4. Showing code examples
    • 8.4.5. Inline markup
    • 8.4.6. Cross-linking markup
    • 8.4.7. Paragraph-level markup
    • 8.4.8. Table-of-contents markup
    • 8.4.9. Index-generating markup
    • 8.4.10. Grammar production displays
    • 8.4.11. Substitutions
  • 8.5. Building the documentation
    • 8.5.1. Using make / make.bat
    • 8.5.2. Without make
• 9. Silence Warnings From the Test Suite
• 10. Fixing “easy” Issues (and Beyond)
• 11. Issue Tracking
  • 11.1. Using the Issue Tracker
    • 11.1.1. Checking if a bug already exists
    • 11.1.2. Reporting an issue
  • 11.2. Helping Triage Issues
    • 11.2.1. Classifying Reports
    • 11.2.2. Reviewing Patches
    • 11.2.3. Finding an Issue You Can Help With
  • 11.3. Gaining the “Developer” Role on the Issue Tracker
  • 11.4. The Meta Tracker
• 12. Triaging an Issue
  • 12.1. Fields
    • 12.1.1. Title
    • 12.1.2. Type
    • 12.1.3. Stage
    • 12.1.4. Components
    • 12.1.5. Versions
    • 12.1.6. Priority
    • 12.1.7. Keywords
    • 12.1.8. Nosy List
    • 12.1.9. Assigned To
    • 12.1.10. Dependencies
    • 12.1.11. Superseder
    • 12.1.12. Status
    • 12.1.13. Resolution
    • 12.1.14. Mercurial Repository
  • 12.2. Generating Special Links in a Comment
• 13. Following Jython’s Development
  • 13.1. Mailing Lists
  • 13.2. IRC
  • 13.3. Blogs
• 14. How to Become a Core Developer
  • 14.1. What it Takes
  • 14.2. Gaining Commit Privileges
    • 14.2.1. Mailing Lists
    • 14.2.2. Issue Tracker
    • 14.2.3. SSH
    • 14.2.4. Sign a Contributor Agreement
    • 14.2.5. Read/Write Checkout
  • 14.3. Responsibilities
• 15. Developer Log
  • 15.1. Permissions History
  • 15.2. Permissions Dropped on Request
  • 15.3. Permissions Dropped after Loss of Contact
  • 15.4. Initials of Project Admins
• 16. Committing and Pushing Changes
  • 16.1. Is the change ready for committing?
    • 16.1.1. Does the test suite still pass?
    • 16.1.2. Patch checklist
  • 16.2. Commit Style
  • 16.3. Handling Others’ Code
  • 16.4. Contributor Licensing Agreements
  • 16.5. NEWS Entries
  • 16.6. Commit Messages
    • 16.6.1. Mercurial hooks
• 17. Working with Mercurial
  • 17.1. Minimal Configuration
  • 17.2. Clones Setup
    • 17.2.1. Single Clone Approach
    • 17.2.2. Multiple Clones Approach
  • 17.3. Active branches
  • 17.4. Merging order
  • 17.5. Merging between different branches (within the same major version)
  • 17.6. Porting changesets between the two major Python versions (2.x and 3.x)
  • 17.7. Long-term development of features
    • 17.7.1. Uploading a patch for review
• 18. Development Cycle
  • 18.1. Branches
    • 18.1.1. In-development (main) branch
    • 18.1.2. Maintenance branches
    • 18.1.3. Security branches
    • 18.1.4. Summary
  • 18.2. Stages
    • 18.2.1. Pre-alpha
    • 18.2.2. Alpha
    • 18.2.3. Beta
    • 18.2.4. Release Candidate (RC)
    • 18.2.5. Final
• 19. Continuous Integration
  • 19.1. Checking results of automatic builds
  • 19.2. Stability
  • 19.3. Flags-dependent failures
  • 19.4. Ordering-dependent failures
  • 19.5. Transient failures
  • 19.6. Custom builders
• 20. Experts Index
  • 20.1. Stdlib
  • 20.2. Tools
  • 20.3. Platforms
  • 20.4. Miscellaneous
• 21. Emacs support
• 22. Jython Developer FAQ
  • 22.1. Communications
  • 22.2. Version Control
  • 22.3. SSH
• 23. How To Release Jython
  • 23.1. Post Publish