Skip to content

Latest commit

 

History

History
192 lines (157 loc) · 8.05 KB

CONTRIBUTING.md

File metadata and controls

192 lines (157 loc) · 8.05 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.

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. This will allow you to use the ./manage.py command in your 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.
  • 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.

Repository Layout

  • manage.py - plays the role of a "Makefile", use it to run tests, build documentation, etc. (needs the python plumbum package: pipenv install --dev && pipenv shell)
  • 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)
      • web_workers - supporting files for WebWorker support (worker.js - a javascript worker implementation which loads and executes a python script)
      • brython.js, brython_dist.js, brython_stdlib.js - the Brython release files (generated by scripts/make_dist.py)
      • py_VFS.js concatenated version of the standard library (generated by scripts/make_VFS.py) to avoid delays when importing from the standard library
      • py2js.js the Python parser & compiler (see Brython Internals for more details)
      • py_bytes.js, py_comples.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_import.js, py_import_hooks.js - modules & the import machinery
      • 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

    $ ./manage.py devel 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".

Every commit is tested on Travis CI. To run the same tests locally you first have to install the Testem test runner.

Assuming you have node.js and npm/yarn this can be done via

    $ npm install testem

or

    $ yarn add testem

or

    $ ./manage.py ci get_testem

Running the tests is then just a matter of

    $ ./manage.py ci run_tests

or

    $ ./node_modules/.bin/testem -t www/tests/qunit/run_tests.html ci

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.