# Contributing

This is a guideline for developers.
If you want to use this package, we refer to the README file. 

## Getting started

Clone or download this repository.
Install all dependencies declared in the `requirements.txt` files located in:
- `./requirements.txt`
- `./doc/requirements.txt`
- `./examples/requirements.txt`


### Only for Windows users:

Download and install `gcc`.
Binaries for `gcc` are included in [w64devkit](https://github.com/skeeto/w64devkit/releases).
Create a system or user environment variable called `PATH` 
and append the path `w64devkit\bin` where `gcc.exe` is located.

### Run tests

Try to run all doctest and unittests located in the modules `conforce` and `conforce_shared`.
Additionally, an Abaqus installation is required to execute code of the `conforce_abq` package.

## Test Code

Test code is written:
 - as `Doctest` in the docstrings of modules, classes or functions
 - as `unittest.TestCase`. Modules containing Unit Tests start with `test_` and are placed 
   in a sub-folder of the module called `tests`.

## Documentation

Sphinx is used to create the documentation.
To build the documentation open a shell and change to the doc directory

``` shell
cd doc
```

Delete the generated toctree before generating a sphinx doc.
This prevents warnings.

``` shell
rm -r source/generated
```

Finally, the documentation is generated by

``` shell
make html
```

and can be opened by

``` shell
start build/html/index.html
```

If sphinx raises a warning, check if the warning can be easily fixed.

Furthermore, [readthedocs](https://readthedocs.io) is used to create an only documentation.

## Release

To create a new release, follow the steps:

1. ```shell
   make_plugin.bat
   ```
   This puts files for the Abaqus plugin into a zip-file in the release folder.
2. Create a new tag named `v{version-string}`
3. ```shell
   git push --tags
   ```
   Upload the tag to remote repository.
4. Open the remote repository in the browser and create a new release.
   1. Choose the uploaded tag and the main branch as target.
   2. If the version is in the "alpha" or "beta" stage, check "Set as pre-release".
   3. Upload the zip-file containing the Abaqus plugin from the release folder as binary.
   4. (Optional) Describe changes to the previous release
5. Click *Publish release*
6. Build a new documentation in readthedocs.
7. ```shell
   upload_to_pypi.bat
   ```
   Upload Python 3 package to PyPi

## Conventions and Guidelines

The following is a set of guidelines and conventions.

### Packages
    
- The package
  - `conforce_gen` contains modules that require Python 3 and do not run in Abaqus Python
  - `conforce_abq` contains modules that require Abaqus Python and do not run in Python 3
  - `conforce` contains modules that run in both, Abaqus Python and Python 3

### Naming Conventions

The naming conventions follow the [Style Guid for Python Code](https://peps.python.org/pep-0008/).
However, there are a few exceptions.


#### Variables

- A mathematical naming convention is used for variables.
  - Matrices and vectors are upper case.
  - Scalars are lower case except for quantities that are only known upper case like:
    - the youngs modulus `E`
    - the J-Integral `J`
  - Matrix components are scalars and thus are lower case. The index is written without an underscore. 
    E.g. `X = [x0, x1, x2]`
  - If (sympy) symbols and concrete values are used simultaneously, the variable for the concrete value ends with an underscore. E.g.:
    `U` (symbolic displacements) and `U_` (numpy array of displacements)
  - Variables referring to specific points are named according to `{variable_name}_at_{point_name}`.
  - The derivative of `H` with respect to `R` is written as `dH_dR`.

#### Functions

- Function names are lower case except they refer to a mathematical symbol that is written upper case 
  (e.g. `eval_H` refers to `H` the matrix of shape functions)

### Versioning
Use [Semantic Versioning](https://semver.org/spec/v2.0.0.html): `{major}.{minor}.{patch}[-{modifier}]`
The modifier is optional.