.. _contribindex:

Contributing to Arbor
=====================

First off, thank you for considering contributing to Arbor! It’s people
like you that make Arbor such a great tool. Feel welcome and read the
following sections in order to know how to ask questions and how to work
on something.

.. _contribindex-types:

Types of contributions
----------------------

There are many ways to contribute: sharing models, writing tutorials or blog posts,
improving the documentation, helping other users, submitting bug reports
and feature requests or writing code which can be incorporated into
Arbor itself.

Use the `Arbor Discussions <https://github.com/arbor-sim/arbor/discussions>`__
page for support questions.

.. _contribindex-github:

Github
------

Arbor uses Git for version control and Github to host its code
repository and nearly all of its infrastructure.

-  If you’re not familiar with Git or Github, please have at look at
   `this introduction <https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/set-up-git>`__.
-  Make sure you have a `GitHub
   account <https://github.com/signup/free>`__.

.. _contribindex-model:

Model
~~~~~

Sharing research and findings that used Arbor is the best contribution you can make to the project.

- We encourage the use of our Github Discussions board for public discussions on modelling: `Github Discussions <https://github.com/arbor-sim/arbor/discussions>`_.

- Users can share their models by adding them to the model collection on GitHub at `arbor-contrib <https://github.com/arbor-contrib/>`_.

.. _contribindex-discuss:

Start a discussion
~~~~~~~~~~~~~~~~~~

You can use the `Arbor
Discussions <https://github.com/arbor-sim/arbor/discussions>`__ to help
other users of Arbor, or get help with you own simulations. Also, we’re
eager to discover what you’re using Arbor for, so don’t hesitate to
share your Arbor simulations or publications!

.. _contribindex-fileissue:

Filing an issue
~~~~~~~~~~~~~~~

If you have found a bug or problem in Arbor, or want to request a feature, you
can use our `issue tracker <https://github.com/arbor-sim/arbor/issues>`__. If
you issue is not yet filed in the issue tracker, please do so and describe the
problem, bug or feature as best you can. You can add supporting data, code or
documents to help make your point. For bugs in particular, stacktraces (either
from inside a debugger or by enabling ``ARB_BACKTRACE``) are extremely useful.

.. _contribindex-solveissue:

Help solving an Issue
~~~~~~~~~~~~~~~~~~~~~

If you want to help solve an issue, that’s great! Issue labels can help
you find an something that fits your expertise or interest, and if
you’re just getting started, you can look for the “`good 1st
issue <https://github.com/arbor-sim/arbor/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+1st+issue%22>`__”
label. Don’t hesitate to post a comment to the Issue if you want to ask
clarifying questions. If you have implemented a fix, you can make a pull
request.

Write code
~~~~~~~~~~

Some tips when contributing code:

-  Consider the :ref:`contribcodingstyle`.
-  If you add functionality, please update the documentation
   accordingly.
-  If you add functionality, add tests if applicable. This helps make
   sure Arbor is stable and functionality does what it’s supposed to
   do.
-  If you work on the public C++ API, provide Python wrappings.
-  Make sure Arbor compiles and has no new warnings.

Add examples or unit tests
~~~~~~~~~~~~~~~~~~~~~~~~~~

See :ref:`contribexample` and :ref:`contribtest`.

Modify documentation
~~~~~~~~~~~~~~~~~~~~

See :ref:`contribdoc`.

Making a pull request
~~~~~~~~~~~~~~~~~~~~~

See :ref:`contribpr`.

.. _contribindex-other:

Other contributions
-------------------

We try to collect models scientists have built in our `contributor space <https://github.com/arbor-contrib/>`_.
In addition to the tutorials, browsing these models should give you a good idea of what's possible with Arbor
and find get in contact with other Arbor users.

We're always happy to hear about Arbor being used! Have you used Arbor to create a model?
Have you used Arbor in a publication? Do you have a workflow or tool that involves Arbor?
Get in touch and we'd be very happy to showcase your work through our channels.

.. _contribindex-coc:

Code of Conduct
---------------

We have a brief code of conduct which we ask you to respect:

* We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or any other characteristic.
* Please avoid using overtly provoking aliases or nicknames that might detract from a friendly, safe and welcoming environment for all.
* Please be kind and courteous. There’s no need to be mean or rude.
* Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs.
* Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works.

Concerns
~~~~~~~~

If you believe one of these standards has been violated, you can reach out to the Arbor project by email, `concern@arbor-sim.org <mailto:concern@arbor-sim.org>`_. Nora Abi Akar, Thorsten Hater, Brent Huisman and Sam Yates read this inbox and will get back to you in a timely manner. Your complaint and the private information therein will be handled with the utmost care and confidentiality. Alternatively, you can contact someone outside of the Arbor team at Ebrains, `see below <#ebrains>`_.

In general, violations of the community standards will generate one or more of the following responses from the Arbor Team:

1. Informal feedback, privately and/or (for public violations) in the forum where a violation appeared, with the goal of encouraging good-faith contributions and mutual understanding while making offenders aware of the problem and preventing future incidents. Where possible, good intentions of the participants should be assumed.
2. Gross online violations of community standards may result in immediate deletion of the offending comments, coupled with informal feedback.
3. For severe cases, especially persistent, disruptive violations despite repeated warnings and other feedback, a formal investigation may be started through the Ebrains Ombudsperson.

Ebrains
~~~~~~~

Arbor is an Ebrains/HBP project. Its policies and recourse options in case of concern are therefore available to you. In addition, the European Commission recognizes the ALLEA Code of Conduct as a model for all research it funds, which includes Ebrains/HBP/Arbor.

* `Ebrains Terms <https://ebrains.eu/terms>`_
* `ALLEA Code of Conduct <https://allea.org/code-of-conduct>`_
* `Ebrains Point of registration for ethical concerns <https://www.humanbrainproject.eu/en/social-ethical-reflective/about/register-ethical-concern/>`_
* `Ebrains Ombudsperson <mailto:research-integrity@ebrains.eu>`_

.. _contribindex-contact:

Get in touch
------------

You can reach out in the following ways:

-  `Discussions <https://github.com/arbor-sim/arbor/discussions>`__. Any
   questions or remarks regarding using Arbor for your research are
   welcome.
-  `Gitter <https://gitter.im/arbor-sim/community>`__. If you’re interested in
   developing Arbor itself, get in touch on Gitter.
-  `Email <mailto:contact@arbor-sim.org>`__.
