************
Contributing
************

Issues
======

Please report bugs or feature requests by `creating GitHub issues`_.

.. _creating GitHub issues: https://github.com/aas-core-works/aas-core3.0-python-protobuf/issues

In Code
=======

If you want to contribute in code, pull requests are welcome!

Please do `create a new issue`_ before you dive into coding.
It can well be that we already started working on the feature, or that there are upstream or downstream complexities involved which you might not be aware of.

.. _create a new issue: https://github.com/aas-core-works/aas-core3.0-python-protobuf/issues

Code Generation
===============

The code for the conversion model instance ⟷ Protocol Buffer has been automatically generated by `aas-core-codegen`_.
It probably makes most sense to change the generator rather than add new functionality.
However, this needs to be decided on a case-by-case basis.

.. _aas-core-codegen: https://github.com/aas-core-works/aas-core-codegen

To re-generate the conversion code, run ``dev_scripts/generate_pbization.py``:

.. code-block::

	python dev_scripts/generate_pbization.py

The code for managing Protocol Buffers has been generated using `protoc`_.
You have to have `protoc`_ installed.

.. _protoc: https://grpc.io/docs/protoc-installation/

To re-generate the code for Protocol Buffer management, run:

.. code-block::

	python dev_scripts/run_protoc.py

Test Data
=========

The test data is automatically generated by `aas-core3.0-testgen`_, and copied to this repository on every change.

.. _aas-core3.0-testgen: https://github.com/aas-core-works/aas-core3.0-testgen

New Versions of the Meta-model
==============================
If there is a new patch version of the meta-model, you have to:

* Update the Protocol Buffer definitions in ``dev_scripts/proto`` (see also ``dev_scripts/update_proto_definition.py``),
* Re-generate the code for the management of Protocol Buffers (see above), and
* Update the ``aas-core-meta`` commit hash in ``requirements-dev.txt`` and install the newest version, and
* Re-generate the conversion code (see above).

Pre-commit Checks
=================

Before you can run pre-commit checks, you need to all the dependencies as well as the development dependencies.
Run in your virtual environment:

.. code-block::

    pip3 install --editable .
    pip3 install -r requirements-dev.txt

Now you can execute the checks (from the repository root):

.. code-block::

    python continuous_integration/precommit.py

Some of the checks, such as formatting, can be automatically fixed.
If you want a self-healing checks, run:

.. code-block::

    python continuous_integration/precommit.py --overwrite

Pull Requests
=============

**Feature branches**.
We develop using the feature branches, see `this section of the Git book`_.

.. _this section of the Git book: https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows

If you are a member of the development team, create a feature branch directly within the repository.

Otherwise, if you are a non-member contributor, fork the repository and create the feature branch in your forked repository.
See `this GitHub tutorial`_ for more guidance.

.. _this GitHub tutorial: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork

**Branch Prefix**.
Please prefix the branch with your Github user name (*e.g.,* ``mristin/Add-some-feature``).

**Continuous Integration**. 
GitHub will run the continuous integration (CI) automatically through GitHub actions.
The CI includes running the tests, inspecting the code, re-building the documentation *etc.*

Commit Messages
===============

The commit messages follow the guidelines from https://chris.beams.io/posts/git-commit:

* Separate subject from body with a blank line,
* Limit the subject line to 50 characters,
* Capitalize the subject line,
* Do not end the subject line with a period,
* Use the imperative mood in the subject line,
* Wrap the body at 72 characters, and
* Use the body to explain *what* and *why* (instead of *how*).