Skip to content

Latest commit

 

History

History
192 lines (155 loc) · 8.34 KB

CONTRIBUTING.md

File metadata and controls

192 lines (155 loc) · 8.34 KB
Raw

How to contribute

In the Brython project we welcome contributions from everyone. There are many ways how you can contribute and not all of them require you to be proficient in Python or Javascript (though some knowledge of at least one of these is of course necessary). Also contributions are not limited to coding. We also welcome

  • contributions to the documentation
  • participating in discussions on the mailing list
  • filing and/or triaging issues on GitHub
  • talking about Brython at conferences, blogging about it, promoting it in forums
  • giving information about the applications developed with it

Please note that we do not welcome financial contributions. Although we appreciate the good intentions, in our opinion, these would ruin the fun of the project and introduce a risk of tensions between the core team and contributors paid for their work on Brython. Our policy is quite strict in this regard and we do not accept them in any form (bounties, ...). If you like Brython and would like to express your appreciation for the project financially, consider donating to the Python Software Foundation.

The documentation included in the project and on brython.info is provided in English and French. Translations in other languages are very much appreciated, but because it is important that the official documentation remains up-to-date, they should be developed in a fork of the project.

Getting Started

  • Make sure you have a GitHub account.
  • Create an Issue on Github, assuming one does not already exist. Clearly describe the issue including steps to reproduce when it is a bug.
  • Fork the repository on GitHub.
  • clone your repo using git
  • (optionally) install the development requirements using pipenv (strongly recommended):
    $ pipenv install --dev

or (not recommended)

    $ pip install -r requirements.txt

If you used pipenv, the development requirements are installed into a separate virtual environment which you can activate by running

    $ pipenv shell

from the terminal.

Making Changes

  • Create a topic branch from where you want to base your work. To quickly create a topic branch based on master, run
    $ git checkout -b fix/master/my_contribution master
  • Make commits of logical units.
  • For Javascript code, there is a Javascript coding style. It is not mandatory and pull requests won't be rejected for this reason, but it helps having a uniform style for all scripts.
  • Check for unnecessary whitespace with git diff --check before committing.
  • Make sure your commit messages are in the proper format. If the commit addresses an issue on Github, start the first line of the commit with the issue number in parentheses.
  • If possible, write a unit-test for your changes (see below).
  • Run all the test suite (see below) to ensure nothing else was accidentally broken.

Creating distribution

Run make_dist.py script with a CPython interpreter of the same version as Brython (eg CPython 3.8 for Brython 3.8) to generate these files after changing the source:

  • www/src/brython.js
  • www/src/brython_stdlib.js
  • www/src/stdlib_paths.js
  • www/src/version_info.js
cd scripts
python3 make_dist.py

Repository Layout

  • scripts - miscellaneous release helper scripts
  • www
    • doc - directory with documentation (as visible here); documentation is generated using the scripts/make_doc.py script.
    • gallery - a directory containing example Brython programs (see Gallery)
    • src
      • Lib - Brython implementation of the modules from Python's standard library. Quite a few files here are just copies of the corresponding file from the CPython distribution; The files here are written in Python.
      • libs - Javascript implementation of some modules from the standard library (for which a Python implementation is either too slow or cumbersome)
      • brython.js, brython_stdlib.js - the Brython release files (generated by scripts/make_dist.py)
      • python_tokenizer.js the Python tokenizer (produces tokens similar to those produced by the CPython tokenize module)
      • py2js.js the Python parser & compiler (see Brython Internals for more details)
      • loaders.js executes the tasks created by py2js.js (mostly related to imports) and runs the scripts
      • brython_builtins.js - initialize attributes of the object __BRYTHON__
      • py_bytes.js, py_complex.js, py_dict.js, py_float.js, py_int.js, py_list.js, py_long_int.js, py_set.js, py_string.js, py_range_slice.js - Javascript implementations of Python types
      • py_generator.js - Javascript implementation of generators
      • py_exceptions.js - Basic implementation of Exceptions
      • py_builtin_functions.js - Implementation of Python builtins
      • py_object.js - Implementation of Python Objects (see Brython Internals for more details)
      • py_utils.js - various utility functions used at compile or execution time
      • py_import.js- the import machinery
      • async.js - conversion for async features (Python coroutines / Javascript promises)
      • js_objects.js - Python <-> Javascript interface (code for accessing external javascript objects from Python and vice versa)
      • builtin_modules.js - implementation of some Brython specific modules (html, browser, ...)

Testing

Testing changes in development

Running

    $ python3 server.py

or if Brython was installed by pip:

    $ brython-cli --server

in a terminal window opened in the checkout directory should open a browser window with a local copy of the www.brython.info website. You can use the console and editor sections to try out your changes to Brython.

Running the test suite before committing

Navigating to localhost:8000/tests you can run the full Brython test suite manually by clicking on "Run all tests".

Writing tests

To prevent regressions, it is good practice to write tests for the bugs you fix or the features you add. These tests live in the www/tests subdirectory. Tests for bugs should go into the file www/tests/issues.py (just add your test to the end of the file, preceding it with a comment mentioning the issue number on Github and the issue title). Tests for substantial new functionality should go into their own separate file (e.g. www/tests/test_webworkers.py). This file should then be included in www/tests/brython_test_utils/__init__.py by adding a line to the discover_brython_test_modules method.

All tests currently use plain assert statements (no unittest/setup/teardown).

Submitting Changes

  • Push your changes to a topic branch in your fork of the repository.
  • Submit a pull request to the Brython repository

Additional Resources

Acknowledgements

Parts of the document copied from / based on Puppet contributing guide.