61 lines
5.4 KiB
Markdown
61 lines
5.4 KiB
Markdown
_model: page
|
||
---
|
||
title: Your First VOC contribution
|
||
---
|
||
body:
|
||
|
||
About VOC
|
||
----------
|
||
|
||
The idea behind VOC is to take Python bytecode, and compile it directly to Java bytecode. This means your .py file will be converted in a .class file that can be executed in a Java Virtual Machine.
|
||
|
||
This is useful in a number of possible ways:
|
||
|
||
* Writing Android applications
|
||
* Writing ElasticSearch/Lucene plugins
|
||
* Writing Minecraft plugins
|
||
* Writing web applications for situations where JavaEE is the only available deployment platform.
|
||
|
||
It’s similar to Jython in that it allows you to run Python on Java; but it’s different because there’s no runtime “executable” - it’s not a Python interpreter written in Java; it generates Java bytecode that is indistinguishable from code that was generated using `javac`.
|
||
|
||
Before you start
|
||
-----------------
|
||
|
||
In the following instructions, we're going to assume you’re familiar with `Github and making pull requests </contributing/how/first-time/github>`__. I'm also going to assume some entry level Python and Java; if anything described here doesn’t make sense, don’t worry - we're more than happy to fill in the gaps. At this point, we don’t know what you don’t know :-)
|
||
|
||
We're also going to assume that you’re interested in contributing code; if your interests/skills are elsewhere (e.g., testing, documentation), let us know, and we can make some other suggestions.
|
||
|
||
Before you make your first contribution, take VOC for a spin. The instructions in the `getting started guide <https://voc.readthedocs.io/en/latest/tutorial/tutorial-0.html>`__ should be enough to get going. If you get stuck, let us know and we’ll help you out. And if you get stuck, that will also point to your first contribution - work out what instructions would have made you *not* get stuck, and contribute an update to the README.
|
||
|
||
Your first contribution
|
||
------------------------
|
||
|
||
Once you’ve got VOC working, you’ll be ready to make your first code contribution. The `contribution guide <https://voc.readthedocs.io/en/latest/how-to/contribute.html>`__ will guide you through the process of setting up your development environment. Work through that guide until you can run the VOC test suite - once you've been able to run the test suite without any failures, you're ready to add some new code to the VOC codebase.
|
||
|
||
In order to make Java bytecode behave like Python, VOC needs to implement all the eccentricities of Python behavior. For example, Python allows you to multiply a string by an integer, resulting in a duplicated string (e.g., ``“foo” * 3`` => ``“foofoofoo”``). This *isn’t* legal Java, however; so we need to provide a Java library that implements this behavior.
|
||
|
||
That particular example (string times number) is already implemented - see `the source code for Str.java <https://github.com/beeware/voc/blob/b35b133ae14843326ca09c77f2cd4cf96b6b8d7d/python/common/org/python/types/Str.java#L424>`__. This implements ``__mul__()`` (the Python multiplication method) on a ``Str`` object. It’s implemented in Java, but it implements Python behavior.
|
||
|
||
If you then look at the code for `test_str.py <https://github.com/beeware/voc/blob/master/tests/datatypes/test_str.py>`__, you’ll see the tests for this behavior. We’ve already written a test suite that tries to perform every operation on every data type. However, all of the names listed in that file are the examples that are known to fail (because the implementation doesn’t exist yet). The tests work by writing a short program that implements one mathematical operation, running the program under normal Python, and then running it again under VOC/Java. The test passes when the two executions produce identical output.
|
||
|
||
So - your first open source contribution: Pick a test that is currently listed in the ``test_str.py`` test file (e.g., test_multiply_float is the test of multiplying a string by a float), and modify the implementation of Str until you get the same output from CPython program as you do from VOC-compiled version of the same program. This includes error messages - if CPython raises a ``TypeError`` for a particular operation (e.g., ``“foo” * 3.1415``), then so should VOC - and the error message should be the same too, right down to the punctuation.
|
||
|
||
Before you start work, visit `Ticket #36 <https://github.com/beeware/voc/issues/36>`__ and register which function you're working on - that way we won't end up with 2 people working on the same one.
|
||
|
||
Once you've written your implementation, run the tests. If you get an “unexpected success” from the test suite, and you *don’t* get any failures, you’ve done it! Delete the line from ``test_str.py`` file corresponding to the test you’ve fixed (because the test is no longer expected to fail), and submit a pull request!
|
||
|
||
Celebrate!
|
||
-----------
|
||
|
||
Then break out a celebratory beverage of your choice! You’re an open source contributor!
|
||
|
||
Best of luck - and we can’t wait to see your first contribution!
|
||
---
|
||
summary: So you want to contribute to an Open Source project? VOC is a great place to start.
|
||
---
|
||
gutter:
|
||
|
||
Getting Help
|
||
-------------
|
||
|
||
If you have any difficulties with this tutorial, or there's anything you don't understand, don't forget - we're here to help you. `Get in touch </community/getting-help/>`__ and we'll help you out, whether it's giving a better explanation of what is required, helping to debug a difficult problem, or pointing you towards tutorials for background that you may require.
|