By contributing to Coconut, you agree to your contribution being released under Coconut's Apache 2.0 license.
Anyone is welcome to submit an issue or pull request! The purpose of this document is simply to explain the contribution process and the internals of how Coconut works to make contributing easier.
If you are considering contributing to Coconut, you'll be doing so on the develop
branch, which means you should be viewing the develop
version of the Contributing Guidelines, if you aren't doing so already.
If you are thinking about contributing to Coconut, please don't hesitate to ask questions at Coconut's Gitter! That includes any questions at all about contributing, including understanding the source code, figuring out how to implement a specific change, or just trying to figure out what needs to be done.
Contributing to Coconut is as simple as
develop
branch, andNote: Don't forget to add yourself to the "Authors:" section in the docstrings of any files you modify!
Want to help out, but don't know what to work on? Head over to Coconut's open issues and look for ones labeled "contributor friendly." Contributor friendly issues are those that require less intimate knowledge of Coconut's inner workings, and are thus possible for new contributors to work on.
First, you'll want to set up a local copy of Coconut's recommended development environment. For that, just run git checkout develop
and make dev
. That should switch you to the develop
branch, install all possible dependencies, bind the coconut
command to your local copy, and set up pre-commit, which will check your code for errors for you whenever you git commit
.
Then, you should be able to use the Coconut command-line for trying out simple things, and to run a paired-down version of the test suite locally, just make test-basic
.
After you've tested your changes locally, you'll want to add more permanent tests to Coconut's test suite. Coconut's test suite is primarily written in Coconut itself, so testing new features just means using them inside of one of Coconut's .coco
test files, with some assert
statements to check validity.
DOCS.md
FAQ.md
HELP.md
Makefile
setup.py
requirements.py
and constants.py
to install Coconut. Also reads README.rst
to generate the PyPI description.conf.py
coconut
__coconut__.py
__init__.py
%coconut
IPython magic.__main__.py
main
from main.py
.constants.py
convenience.py
cmd
, version
, setup
, and parse
functions as convenience utilities when using Coconut as a module. Documented in DOCS.md
.exceptions.py
highlighter.py
main.py
main
and main_run
, the entry points for the coconut
and coconut-run
commands, respectively.requirements.py
constants.py
into a form setup.py
can use, as well as checks for updates to Coconut's dependencies.root.py
root.py
creates and executes the part of Coconut's header that normalizes Python built-ins across versions. Whenever you are writing a new file, you should always add from coconut.root import *
to ensure compatibility with different Python versions. root.py
also sets basic version-related constants.terminal.py
logger
, which is Coconut's primary method of logging a message from anywhere.__init__.py
command.py
.cli.py
ArgumentParser
object used to parse Coconut command-line arguments.command.py
Command
, whose start
method is the main entry point for the Coconut command-line utility.mypy.py
--mypy
flag.util.py
command.py
, including Prompt
for getting syntax-highlighted input, and Runner
for executing compiled Python.watch.py
--watch
flag.__init__.py
compiler.py
.compiler.py
Compiler
, the class that actually compiles Coconut code. Compiler
inherits from Grammar
in grammar.py
to get all of the basic grammatical definitions, then extends them with all of the handlers that depend on the compiler's options (e.g. the current --target
). Compiler
also does pre- and post-processing, including replacing strings with markers (pre-processing) and adding the header (post-processing).grammar.py
Grammar
, the class that specifies Coconut's grammar in PyParsing. Coconut performs one-pass compilation by attaching "handlers" to specific grammar objects to transform them into compiled Python. grammar.py
contains all basic (non-option-dependent) handlers.header.py
getheader
, which generates the header at the top of all compiled Coconut files.matching.py
Matcher
, which handles the compilation of all Coconut pattern-matching, including match
statements, destructuring assignment, and pattern-matching functions.util.py
grammar.py
.header.py_template
header.py
.__init__.py
icoconut/root.py
.__main__.py
root.py
__coconut__.pyi
__coconut__.py
).tests
__init__.py
main_test.py
.__main__.py
make test
, or a pytest
command to run a specific test, is necessary.main_test.py
TestCase
subclasses that run all of the commands for testing the Coconut files in src
.src
extras.coco
convenience.py
and icoconut.runnable.coco
--arg
was passed when running the file.runner.coco
main
from cocotest/agnostic/main.py
.cocotest
__init__.coco
main.coco
asserts exists.main.coco
specific.coco
--target
.suite.coco
util.coco
.tutorial.coco
TUTORIAL.md
.util.coco
suite.coco
.py2_test.coco
--target 2
.py3_test.coco
--target 3
.py35_test.coco
--target 3.5
.make check
and update dependencies as necessarymake format
compiled-cocotest
and pyprover
coconut
and compiled-cocotest
) and LGTM alertscoconut-develop
package looks goodmake docs
and ensure local documentation looks gooddevelop
in root.py
root.py
to new version numberroot.py
to new version namedevelop
into master
sublime-coconut
first if applicablemaster
on GitHubmaster
locallymake upload
develop
locallydevelop
in root
make dev
develop
conda-forge
feedstock