Contibuting to gsapy

Do you find gsapy exciting and want to improve it or add a function that you need for your project? Great! This document lays out how to contribute new code to gsapy.

The gsapy Way

When you are adding functionality to gsapy, please keep in mind that gsapy is intended to resemble python. This means that:

1. One action should be triggered by one function call (no set up function calls)

2. Data should be returned in python native data strutures.

3. If an error occurs, you should raise a GSAError (not return a different value).

Branches

gsapy’s main development branch is main. This is the branch where new development works. The latest stable version of gsapy is in a branch called latest.

Please open an issue in the gsapy repo to propose and discuss your changes before submitting a pull request.

The procedure for making changes to gsapy and getting them incorporated into the development branch is as follows:

1. Clone the repository.

   1. if you are just making a one-off contribution, first fork gsapy on github, then clone your fork.

   2. if you will be contributing regularly, you can request Developer access to the gsapy project.

2. Checkout the main branch, then create a new topic branch. For example, if you will be adding a GroundSpring class, create a branch called ‘ground-spring’.

3. Make your changes! This should include:

   1. the new code

   2. documentation: add docstrings to your classes and functions and regenerate the documentation

   3. tests: add tests to check that the new functionality you added works. These will be also be used to make sure future changes don’t break your code.

4. Run the test suite to see if anything has broken. (Run ‘pytest’ in the ‘gsapy/tests’ folder.)

5. Push your feature branch. If you forked gsapy, push it to your fork, otherwise, push it to gsapy directly.

6. Create a merge request to github.com/arup-group/gsapy. The merge request’s source branch will be your topic branch, and the target branch will be arup-group/gsapy : main. If you are working from a forked repository, you create the merge request from your fork.

7. After code review (which may involve some changes), the code will be merged into the main branch.

8. final step: delete your topic branch - thanks for contributing to gsapy!

Tests

Add your tests to gsapy/tests/test_gsapy.py. Refer to the other tests in that file for how to set up tests.

(TODO: we should describe how to write good tests.)

Run the tests by running the command ‘pytest’ in the gsapy/tests folder.