Skip to content

Latest commit

 

History

History
114 lines (92 loc) · 5.63 KB

CONTRIBUTING.rst

File metadata and controls

114 lines (92 loc) · 5.63 KB
Raw

Contributing to formulas

If you want to contribute to formulas and make it better, your help is very welcome. The contribution should be sent by a pull request. Next sections will explain how to implement and submit a new excel function:

  • clone the repository
  • implement a new function/functionality
  • open a pull request

Clone the repository

The first step to contribute to formulas is to clone the repository:

  • Create a personal fork of the formulas repository on Github.
  • Clone the fork on your local machine. Your remote repo on Github is called origin.
  • Add the original repository as a remote called upstream, to maintain updated your fork.
  • If you created your fork a while ago be sure to pull upstream changes into your local repository.
  • Create a new branch to work on! Branch from dev.

How to implement a new function

Before coding, study the Excel function that you want to implement. If there is something similar implemented in formulas, try to get inspired by the implemented code (I mean, not reinvent the wheel) and to use numpy. Follow the code style of the project, including indentation. Add or change the documentation as needed. Make sure that you have implemented the full function syntax, including the array syntax.

Test cases are very important. This library uses a data-driven testing approach. To implement a new function I recommend the test-driven development cycle. Hence, when you implement a new function, you should write new test cases in test_cell/TestCell.test_output suite to execute in the cycle loop. When you think that the code is ready, add new raw test in test/test_files/test.xlsx (please follow the standard used for other functions) and run the test_excel/TestExcelModel.test_excel_model. This requires more time but is needed to test the array syntax and to check if the Excel documentation respects the reality.

When all test cases are ok (python setup.py test), open a pull request.

Do do list:

  • Study the excel function syntax and behaviour when used as array formula.
  • Check if there is something similar implemented in formulas.
  • Implement/fix your feature, comment your code.
  • Write/adapt tests and run them!

Tip

Excel functions are categorized by their functionality. If you are implementing a new functionality group, add a new module in formula/function and in formula.function.SUBMODULES and a new worksheet in test/test_files/test.xlsx (please respect the format).

Note

A pull request without new test case will not be taken into consideration.

How to open a pull request

Well done! Your contribution is ready to be submitted:

  • Squash your commits into a single commit with git's interactive rebase. Create a new branch if necessary. Always write your commit messages in the present tense. Your commit message should describe what the commit, when applied, does to the code – not what you did to the code.
  • Push your branch to your fork on Github (i.e., git push origin dev).
  • From your fork open a pull request in the correct branch. Target the project's dev branch!
  • Once the pull request is approved and merged you can pull the changes from upstream to your local repo and delete your extra branch(es).

Donate

If you want to support the formulas development please donate and add your excel function preferences. The selection of the functions to be implemented is done considering the cumulative donation amount per function collected by the campaign.

Note

The cumulative donation amount per function is calculated as the example:

Function Donator 1 Donator 2 Donator 3 TOT Implementation order
150€ 120€ 50€
SUM 50€ 40€ 25€ 125€ 1st
SIN 50€   25€ 75€ 3rd
TAN 50€ 40€   90€ 2nd
COS   40€   40€ 4th