<commit_before>.. Contribution documentation for libCellML

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

This document covers the process to follow for getting your changes into the :term:`prime repository`.  While there are many types of contribution, this section focuses on contributions made through GitHub and Git, or in other words assets that are managed using the version control system.  It is assumed that :doc:`Setup <dev_setup>` and :doc:`Building <dev_building>` have already been read and followed.

.. contents::

Overview
========

For any body of work intended for the :term:`prime repository` start with a GitHub issue.  The issue can be used to discuss the topic and clarify any problems related to it.  Once progress has been made towards addressing the issue a pull request is created that references the issue.

Reviewers provide feedback on the changes by adding comments to the pull request or associated commits. The BuildBot build/test procedure will run each time changes are pushed to the pull request's branch, and the results are displayed in the pull request view.

Once all the changes and reviews are complete, one of the :term:`prime repository` owners will merge the pull request into the prime repository, onto the develop branch.

Note that a bug is just a type of issue, and that resolving the bug should have both the implementation to fix the bug and a test that triggers the bug.

:numref:`Figure %s <libcellml-development-process>` gives a graphical overview of the developer contribution process.  For more detail see the text below.

.. _libcellml-development-process:
.. figure:: images/libCellMLProcesses-DevelopmentProcess.png
   :align: center
   :alt: Developer contribution process

   Developer contribution process

GitHub Issue
============

If an issue does not exist for the required work (e.g. implementation of a feature, fixing of a bug), then create a new one.  The issue is the place to discuss the particulars related to the issue, discussions on determining the scope of the issue or clarification of any points that are unclear.

Topic Branch
============

A topic or feature branch is a branch that is local to you (and anyone you collaborate with), it is a branch that will not be available from the :term:`prime repository`.  All development work should be carried out on a topic branch, for example any major feature that you work on or minor bug fix.  Before creating a local topic branch pull the latest changes from the :term:`prime repository` develop branch.

.. _libcellml-branching:
.. figure:: images/libCellMLProcesses-GitBranching.png
   :align: center
   :alt: Git branching illustration

   Git branching illustration

Following this process will make it easier to have multiple topic branches at once and keep them in-sync with the :term:`prime repository` develop branch.  Which will in turn make it easier to manage multiple pull requests.

The following Git command line commands show an example of how to create a topic branch for fixing a (hypothetical) bug described in `issue #46`::

   git fetch prime develop
   git checkout develop # Not required if already on develop branch
   git merge prime/develop
   git checkout -b issue46

Test Driven Development
=======================

Test driven development entails writing a test that covers the intended functionality (this may require a suite of tests to be written) and no more.  The tests will require some skeleton implementation so that the test(s) can compile but by definition not pass, at least not pass all the tests.  The purpose of this is two-fold: 1. writing the test(s) first sets out the intended design which can be shared through a pull request; and  2. the skeleton implementation will include the documentation clearly describing the intended purpose.  Following this contribution process allows others to comment and make corrections before time is spent on the functional code.

It may be necessary to refactor the current design to enable the easiest possible way to add the new feature.  This is a good thing as the quality of the design improves this makes it easier to work with in the future.  Refactoring means improving the code without adding features, and the tests provide validation that the refactored code performs as well as before.<commit_msg>add documentation for the use of labels<commit_after>.. Contribution documentation for libCellML

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

This document covers the process to follow for getting your changes into the :term:`prime repository`.  While there are many types of contribution, this section focuses on contributions made through GitHub and Git, or in other words assets that are managed using the version control system.  It is assumed that :doc:`Setup <dev_setup>` and :doc:`Building <dev_building>` have already been read and followed.

.. contents::

Overview
========

For any body of work intended for the :term:`prime repository` start with a GitHub issue.  The issue can be used to discuss the topic and clarify any problems related to it.  Once progress has been made towards addressing the issue a pull request is created that references the issue.

Reviewers provide feedback on the changes by adding comments to the pull request or associated commits. The BuildBot build/test procedure will run each time changes are pushed to the pull request's branch, and the results are displayed in the pull request view.

Once all the changes and reviews are complete, one of the :term:`prime repository` owners will merge the pull request into the prime repository, onto the develop branch.

Note that a bug is just a type of issue, and that resolving the bug should have both the implementation to fix the bug and a test that triggers the bug.

:numref:`Figure %s <libcellml-development-process>` gives a graphical overview of the developer contribution process.  For more detail see the text below.

.. _libcellml-development-process:
.. figure:: images/libCellMLProcesses-DevelopmentProcess.png
   :align: center
   :alt: Developer contribution process

   Developer contribution process

GitHub Issue
============

If an issue does not exist for the required work (e.g. implementation of a feature, fixing of a bug), then create a new one.  The issue is the place to discuss the particulars related to the issue, discussions on determining the scope of the issue or clarification of any points that are unclear.

Labels
------

A GitHub Issue may be assigned labels by the project administrators to help identify its status at a glance. General labels currently used for libCellML are:

* **Bug**: The issue identifies a malfunction in the current codebase.
* **Feature**: The issue constitutes a request or plan for a new feature.
* **Needs tests**: The issue requires test(s) to be complete. This may refer to a bug report, contributed code, comments, etc. in the issue.
* **Needs documentation**: The issue requires documentation to be complete. This may refer to a bug report, contributed code, comments, etc. in the issue.
* **Needs reviewing**: The issue requires further review from project participants to be complete. This may refer to a bug report, contributed code, comments, etc. in the issue.

In addition, a **Platform** label may be used to identify the issue as specific to a given platform (Windows/Linux/OSX). **Milestone** labels may be used to project when a feature is expected to be complete and/or indicate the priority of a given issue. Higher priority issues will take precedence and therefore be assigned a more immediate (lower) milestone number.

Topic Branch
============

A topic or feature branch is a branch that is local to you (and anyone you collaborate with), it is a branch that will not be available from the :term:`prime repository`.  All development work should be carried out on a topic branch, for example any major feature that you work on or minor bug fix.  Before creating a local topic branch pull the latest changes from the :term:`prime repository` develop branch.

.. _libcellml-branching:
.. figure:: images/libCellMLProcesses-GitBranching.png
   :align: center
   :alt: Git branching illustration

   Git branching illustration

Following this process will make it easier to have multiple topic branches at once and keep them in-sync with the :term:`prime repository` develop branch.  Which will in turn make it easier to manage multiple pull requests.

The following Git command line commands show an example of how to create a topic branch for fixing a (hypothetical) bug described in `issue #46`::

   git fetch prime develop
   git checkout develop # Not required if already on develop branch
   git merge prime/develop
   git checkout -b issue46

Test Driven Development
=======================

Test driven development entails writing a test that covers the intended functionality (this may require a suite of tests to be written) and no more.  The tests will require some skeleton implementation so that the test(s) can compile but by definition not pass, at least not pass all the tests.  The purpose of this is two-fold: 1. writing the test(s) first sets out the intended design which can be shared through a pull request; and  2. the skeleton implementation will include the documentation clearly describing the intended purpose.  Following this contribution process allows others to comment and make corrections before time is spent on the functional code.

It may be necessary to refactor the current design to enable the easiest possible way to add the new feature.  This is a good thing as the quality of the design improves this makes it easier to work with in the future.  Refactoring means improving the code without adding features, and the tests provide validation that the refactored code performs as well as before.
{'fraction_non_alphanumeric': 0.055544231553200166, 'fraction_numerical': 0.0012229922543823889, 'mean_word_length': 4.503645541222658, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6927204', 'n_tokens_mistral': 2238, 'n_tokens_neox': 2136, 'n_words': 1473}