Contributing
============

Getting Started
---------------

TBD


Adding New API
--------------

1. Add the function to ``hpy/tools/autogen/public_api.h``. If the CPython
   equivalent function name is not the same (after removing the leading ``H``,
   add an appropriate CPython function mapping in ``hpy/tools/autogen/conf.py``.
   If the signature is complicated or there is no clear equivalent function,
   the mapping should be ``None``, and follow the directions in the next step.
   Otherwise all the needed functions will be autogenerated.

2. If the function cannot be autogenerated (i.e. the mapping does not exist),
   you must write the wrapper by hand. Add the function to ``NO_WRAPPER`` in
   ``hpy/tools/autogen/debug.py``, and add a ``ctx_fname`` function to
   ``hyp/devel/src/runtime/*.c`` (possibly adding the new file to ``setup.py``),
   add a debug wrapper to ``hpy/debug/src/debug_ctx.c``, add a implementation
   that uses the ``ctx`` variant to ``hpy/devel/include/hpy/cpython/misc.h`` and
   add the declaration to ``hpy/devel/include/hpy/runtime/ctx_funcs.h``.

3. Run ``make autogen`` which will turn the mapping into autogenerated functions

4. Add a test for the functionality

5. Build with ``python setup.py build_ext``. After that works, build with
   ``python -m pip install -e .``, then run the test with ``python -m pytest ...``.
