Jython Developer’s Guide¶
This guide is a comprehensive resource for contributing to Jython – for both new and experienced contributors. It has been (somewhat incompletely) adapted from the CPython Developer’s Guide and the reader should bear in mind that:
The Jython process, like CPython’s, is based GitHub PRs, but Jython does not have the same set of tool integrations.
Jython migrated from Mercurial in 2020, much later than CPython, so Jython-specific parts of the guide may refer to the old process.
Statements about “Python” should apply to both CPython and Jython. The adaptation is imperfect: parts of the guide will say (or mean) CPython.
This guide is maintained by the same community that maintains CPython and Jython. We welcome your contributions to either implementation of Python!
Quick Reference¶
Mercurial¶
Mercurial is no longer used.
The previous official repository at https://hg.python.org/jython
is not current.
GitHub¶
Here are the basic steps needed to get set up and contribute a patch. This is meant as a checklist, once you know the basics. For complete instructions please see the setup guide.
Install and set up Git and other dependencies (see the Get Setup page for detailed information).
Fork the Jython GitHub repository to your GitHub account and get the source code using:
git clone https://github.com/<your_username>/jython
Build Jython using:
ant
issued in the base check-out directory. The built application will be in subdirectory
dist
. See also more detailed instructions, and how to build dependencies.-
dist/bin/jython -m test.regrtest -e
This applies for Jython 2.7. To test Jython 3, when it exists, replace
test.regrtest
withtest
. Create a new branch where your work for the issue will go, e.g.:
git checkout -b fix-issue-12345 master
If an issue does not already exist, please create it on the Jython GitHub repository. The legacy bug tracker still operates (for Jython 2.7 only) but is not preferred. Trivial issues (e.g. typo fixes) do not require any issue to be created: create a PR directly.
Once you fixed the issue, run the tests, and if everything is ok, commit.
Push the branch to your fork on GitHub:
git push -u origin fix-issue-12345
and create a pull request. Include the issue number using GitHub conventions in the pull request description. (Use
bjo-NNNN
if it is from the legacy tracker.)
Note
bpo-NNNN is used by CPython for for bugs.python.org and is picked up by CPython’s GitHub tools. For Jython we need our own naming convention, but cannot yet re-use the CPython tools. We intend to move away from bugs.jython.org to GitHub issues more aggressively that CPython has made the switch.
Note
First time contributors will need to sign the Contributor Licensing Agreement (CLA) as described in the Licensing section of this guide. This requires an account on the CPython’s legacy bug tracker.
Quick Links¶
Here are some links that you probably will reference frequently while contributing to Jython:
Jython GitHub repository (or maybe the Jython issue tracker)
PEPs (Python Enhancement Proposals)
Status of Jython branches¶
Branch |
Schedule |
Status |
First release |
End-of-life |
Comment |
---|---|---|---|---|---|
master |
bugfix |
PSF support for Python 2 ended in 2020 (see PEP 373) but the most recent release of Jython is still Jython 2.7.2 |
|||
3.8 |
features |
This branch is the future of Jython. (It should be master, but is just a gleam in the eye at present.) |
|||
2.5 |
end-of-life |
Final release: Jython 2.5.3 |
Status:
- features:
new features are only added to the master branch, this branch accepts any kind of change.
- bugfix:
bugfixes and security fixes are accepted, new binaries are still released.
- security:
only security fixes are accepted and no more binaries are released, but new source-only versions can be released
- end-of-life:
release cycle is frozen; no further changes can be pushed to it.
Dates in italic are scheduled and can be adjusted.
By default, the end-of-life is scheduled 5 years after the first release. It can be adjusted by the release manager of each branch. Versions older than 2.7 have reached end-of-life. The Jython project follows the Python Software Foundation in the naming of versions of the language (e.g. Jython 2.7 implements Python 2.7), and whether an implementation of that version has reached reached end-of-life. The third element (micro) has bears no relationship to CPython micro-versions.
See also Security branches.
Jython names its releases in the same scheme as CPython.
Each release of Jython is tagged in the source repo with a tag of the form
vX.Y.ZTN
, where X
is the major version, Y
is the
minor version, Z
is the micro version, T
is the release level
(a
for alpha releases, b
for beta, rc
release candidate,
and null for final releases), and N
is the release serial number.
Some examples of release tags: v3.7.0a1
, v3.6.3
, v2.7.14rc1
.
Contributing¶
We encourage everyone to contribute to Python 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.
A number of individuals from the Python community have contributed to a series of excellent guides at Open Source Guides.
Core developers and contributors alike will find the following guides useful:
Guide for contributing to Jython:
Lifecycle of a Patch (Mercurial) (existing process)
Lifecycle of a Pull Request (partly usable future process)
- Beginner tasks to become familiar with the development process
- Advanced tasks for once you are comfortable
Fixing issues found by the buildbots
Helping out with reviewing open pull requests. See how to review a Pull Request.
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.
Proposing changes to Python itself¶
Improving Python’s code, documentation and tests are ongoing tasks that are never going to be “finished”, as Python operates as part of an ever-evolving system of technology. An even more challenging ongoing task than these necessary maintenance activities is finding ways to make Python, in the form of the standard library and the language definition, an even better tool in a developer’s toolkit.
While these kinds of change are much rarer than those described above, they do happen and that process is also described as part of this guide:
Other Interpreter Implementations¶
This guide is specifically for contributing to Jython, that is, Python on the JVM. (While most of the standard library is written in Python, the interpreter core is written in Java and integrates most easily with the Java SE and EE ecosystems).
There are other Python implementations, each with a different focus. Like Jython, 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 reference implementation of Python implemented in C, and the main focus of language development.
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
Jython’s Java coding standard
PEP 8 (Style Guide for Python Code)
- Source code
PEPs (Python Enhancement Proposals)
Additional Resources¶
Anyone can clone the sources for this guide. See Helping with the Developer’s Guide.
- Tool support
Information about editors and their configurations can be found in the wiki
Code of Conduct¶
Please note that all interactions on Python Software Foundation-supported infrastructure is covered by the PSF Code of Conduct, which includes all infrastructure used in the development of Python itself (e.g. mailing lists, issue trackers, GitHub, etc.). In general this means everyone is expected to be open, considerate, and respectful of others no matter what their position is within the project.
Full Table of Contents¶
- 1. Getting Started
- 2. Where to Get Help
- 3. Lifecycle of a Patch (Mercurial)
- 4. Lifecycle of a Pull Request
- 4.1. Introduction
- 4.2. Quick Guide
- 4.3. Step-by-step Guide
- 4.4. Making Good PRs
- 4.5. Making Good Commits
- 4.6. Licensing
- 4.7. Submitting
- 4.8. Converting an Existing Patch from b.p.o to GitHub
- 4.9. Reviewing
- 4.10. Dismissing Review from Another Core Developer
- 4.11. Committing/Rejecting
- 4.12. Crediting
- 5. Running & Writing Tests (Jython)
- 6. Test Coverage in Jython
- 7. Helping with Documentation
- 8. Documenting Python
- 8.1. Introduction
- 8.2. Style guide
- 8.3. reStructuredText Primer
- 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
- 9. Silence Warnings From the Test Suite
- 10. Fixing “easy” Issues (and Beyond)
- 11. Issue Tracking
- 12. Triaging a Jython Issue
- 13. Following Python’s Development
- 14. How to Become a Core Developer
- 15. Committing and Pushing Changes (Mercurial)
- 16. Working with Mercurial
- 17. Accepting Pull Requests
- 18. Development Cycle
- 19. Continuous Integration
- 20. Adding to the Stdlib
- 21. Changing the Python Language
- 22. Experts Index
- 23. How To Release Jython
- 23.1. Making a Releasable Jython
- 23.1.1. Start in the Right Place
- 23.1.2. Tool Check
- 23.1.3. Clone the Repository
- 23.1.4. Changes Preparing for a Release
- 23.1.5. Get the JARs
- 23.1.6. Check the Configuration of the Build
- 23.1.7. Tag the Release
- 23.1.8. Ant Build for Release
- 23.1.9. Gradle Build for Release
- 23.1.10. Test what you built
- 23.1.11. Only now is it safe to
git push
- 23.1.12. Build the Bundles to Publish
- 23.2. Publication
- 23.3. Ready for new work
- 23.1. Making a Releasable Jython
- 24. Exploring Jython’s Internals
- 25. Changing Jython’s Grammar
- 26. Design of Jython’s Compiler
- 26.1. Abstract
- 26.2. Parse Trees
- 26.3. Abstract Syntax Trees (AST)
- 26.4. Memory Management
- 26.5. Parse Tree to AST
- 26.6. Control Flow Graphs
- 26.7. AST to CFG to Bytecode
- 26.8. Introducing JVM Bytecode
- 26.9. Code Objects
- 26.10. Important Files
- 26.11. Known Compiler-related Experiments
- 26.12. References
- 27. Git Bootcamp and Cheat Sheet
- 27.1. Forking CPython GitHub Repository
- 27.2. Cloning The Forked CPython Repository
- 27.3. Listing the Remote Repositories
- 27.4. Setting Up Your Name and Email Address
- 27.5. Enabling
autocrlf
on Windows - 27.6. Creating and Switching Branches
- 27.7. Deleting Branches
- 27.8. Staging and Committing Files
- 27.9. Reverting Changes
- 27.10. Stashing Changes
- 27.11. Committing Changes
- 27.12. Pushing Changes
- 27.13. Creating a Pull Request
- 27.14. Syncing With Upstream
- 27.15. Applying a Patch from Mercurial to Git
- 27.16. Downloading Other’s Patches
- 27.17. Accepting and Merging A Pull Request
- 27.18. Backporting Merged Changes
- 27.19. Editing a Pull Request Prior to Merging
- 28. Jython Developer FAQ
Specific to CPython¶
These are sections from the CPython guide, retained for reference. A comparison with the CPython implementation of a feature will sometimes help you understand the Jython one.
- Getting Started
- Running & Writing Tests
- Increase Test Coverage
- Triaging an Issue
- Porting Python to a new platform
- Developer Log
- Continuous Integration
- gdb Support
- Exploring CPython’s Internals
- Changing CPython’s Grammar
- Design of CPython’s Compiler
- Coverity Scan
- Dynamic Analysis with Clang
- Running a buildslave
- Core Developer Motivations and Affiliations