Your first Batavia contribution

So you want to contribute to an Open Source project, but you don't know how? No problem - Batavia is a great place to start.

Imposter syndrome

There may be a little voice inside your head that is telling you that you're not ready; that you need to do one more tutorial; that you aren't ready to be an open source contributor. After all, you're just a beginner. What could you possibly offer a project like this one?

I assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open source.

You're not the first person to have those thoughts, either. Even the members of the core team of this project have these thoughts from time to time. It's called "imposter syndrome", and it's a really common problem. The good news is - we're here to help you get over it.

This tutorial exists to make sure you know exactly what process you have to follow in order to get your patch merged. In addition to these procedural instructions, this project has a Code of Conduct. This Code of Conduct is there to give you confidence that no matter what mistakes you make, you'll be treated with respect. Everyone makes mistakes - that's a natural part of learning. Our pledge to you is that we are here to help you learn, not to insult or belittle you for learning.

Being an open source contributor doesn't just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you're coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over.

So - don't be afraid to contribute. If you've gotten this far, you've demonstrated you have an interest in contributing - and that's all you need. We can help you the rest of the way.

About Batavia

The idea behind Batavia is to take Python bytecode, and ship it to a browser where it runs in a Javascript implementation of the Python virtual machine.

This means it is possible to write web applications 100% in Python - so those new to web development don't need to learn multiple languages to develop web apps.

In the following instructions, I’m going to assume you’re familiar with Github and making pull requests. I'm also going to assume some entry level Python and JavaScript; if anything I describe here doesn’t make sense, don’t worry - I’m more than happy to fill in the gaps. At this point, I don’t know what you don’t know :-)

This tutorial is also going to focus on code contributions. If your interests/skills are elsewhere (e.g., testing, documentation), let me know, and I can make some other suggestions.

Before you make your first contribution, I’d suggest taking Batavia for a spin. The instructions in the getting started guide should be enough to get going. If you get stuck, let me know and I’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.

Once you’ve got Batavia working, you’ll be ready to make your first code contribution. The contribution guide will guide you through the process of setting up your development environment. Work through that guide until you can run the Batavia 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 Batavia codebase.

In order to implement a full Python virtual machine, Batavia needs to implement all the eccentricities of Python behaviour. For example, Python allows you to multiply a string by an integer, resulting in a duplicated string (e.g., “foo” * 3 => “foofoofoo”). Javascript behaviour can be quite different, depending on circumstances - so we need to provide a library that implements the desired Python behaviour.

That particular example (string times number) is already implemented - see the __mul__ function definition in:

https://github.com/pybee/batavia/blob/master/batavia/types/Str.js

This implements the multiply operator. It’s implemented in Javascript, but it implements Python behaviour - for some data types.

If you then look at:

https://github.com/pybee/batavia/blob/master/tests/datatypes/test_str.py

You’ll see the tests for this behaviour. I’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 Batavia. 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 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 the Batavia 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 Batavia - and the error message should be the same too, right down to the punctuation.

Before you start work, visit ticket #46 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 the test_str file corresponding to the test you’ve fixed (because the test is no longer expected to fail), and submit a pull request!

Then break out a celebratory beverage of your choice! You’re an open source contributor!

If you need help stepping through this, you can grab me on Twitter, or in #beeware on IRC (on Freenode). I’m freakboy3742 on both. Or, feel free to send me an email

Best of luck - and I can’t wait to see your first contribution!