Development#

How to contribute#

Contributions are always welcome. Everything ranging from small extensions of the documentation to implementing new features is appreciated. Of course, the bigger the change the more it is necessary to reach out to us in advance for an discussion. You can post an issue or contact hmgaudecker via email.

To get acquainted with the code base, you can also check out our issue tracker for some immediate and clearly defined tasks.

Please read the following steps carefully before contributing!

  1. Fork the repository. This will create a copy of the repository where you have write access. Your fix will be implemented in your copy. After that, you will start a pull request (PR) which means a proposal to merge your changes into the project. If you plan to become a regular contributor we can give you push access to unprotected branches, which makes the process more convenient for you.

  2. Clone the repository to your disk. Set up the project environment with conda. The commands for this are (in a terminal in the root of your local econ-project-templates repo):

    $ conda env create -f environment.yml
$ conda activate cp

  3. Implement the fix or new feature. If you work on the inner project please read about our recommend workflow in the next section. There we also explain what the inner project is.

  4. We validate contributions in three ways. First, we have a test suite to check the implementation the templates. Second, we correct for stylistic errors in code and documentation using linters. Third, we test whether the documentation builds successfully.

    You can run all checks with pytest by running

    $ pytest

    This will run the complete test suite.

    Correct any errors displayed in the terminal.

    To correct stylistic errors, you can also install the linters as a pre-commit with

    $ pre-commit install

    Then, all the linters are executed before each commit and the commit is aborted if one of the check fails. You can also manually run the linters with

    $ pre-commit run -a

  5. If the tests pass, push your changes to your repository. Go to the Github page of your fork. A banner will be displayed asking you whether you would like to create a PR. Follow the link and the instructions of the PR template. Fill out the PR form to inform everyone else on what you are trying to accomplish and how you did it.

    The PR also starts a complete run of the test suite on a continuous integration server. The status of the tests is shown in the PR. Reiterate on your changes until the tests pass on the remote machine.

  6. Ask one of the main contributors to review your changes. Include their remarks in your changes.

  7. The final PR will be merged by one of the main contributors.

Working on the inner project#

We differentiate between the inner project, which is the example project located in {{cookiecutter.project_slug}}, and the outer project, which is everything else.

To work on the inner project we recommend the following workflow:

  1. Use cookiecutter econ-project-templates locally to create an example project

  2. Create a conda environment in this local example project

  3. Make sure that pytask builds the example project and that the tests run

  4. Apply changes to the example project

  5. Repeat step 3

  6. Transfer changes to the official repository by changing example names to {{cookiecutter.project_slug}} etc.

# Release Notes

## v0.6.3 – January 2023

Incorporate more feedback from EPP students, @janosg:

  • Do not add linters by default, but give an option to add them.

  • Add github actions back in, make codecov meaningful.

## v0.6.2 – January 2023

Incorporate feedback from EPP students, @janosg, @tobiasraabe.

  • Update warning message for R, better explanations for examples and links to issues.

  • Add scripts as explicit dependencies.

  • Use git_remote_url option again.

  • Add yaml linters, run them. Update versions of pre-commit hooks also in inner project.

  • Ditch flake8 in favor of ruff.

  • Get rid of refurb’s complaints.

  • Ignore complexity in post_gen_project.

## v0.6 – December 2022

  • Add R example (#105, @carolinalvarez, @timmens)

  • Complete re-write of example, structure, docs (#98, #108, #111, #115, #118, #119, @timmens)

  • Convert Documentation from reST to Markdown (#117, @mj023)

## v0.5 – January 2022

  • Move to plotly (#92, @timmens)

  • Cleaning up (@hmgaudecker)

## v0.4 – January 2021

  • Move from Waf to Pytask (#86, @tobiasraabe, @hmgaudecker)

  • Move to GitHub Actions for CI (@janosg, WIP)

## v0.3 – October 2019

  • Much improved documentation (@raholler)

  • Extensive instructions for use on Windows (@raholler)

  • Re-use previously-entered data when cookiecutter fails (@tobiasraabe, @raholler)

  • Fix Stata template by setting <span class=”title-ref”>–shell-escape=1</span> (#63, @raholler)

  • Add pyupgrade to pre-commit hooks (#59)

  • Thanks to students at LMU for pointing lots of this out!

## v0.2 – September 2019

  • Full continuous integration testing on the Azure platform

  • R example completely working in Miniconda environment out of the box (@raholler)

  • Documentation for Stata / R examples (@raholler)

  • Much improved instructions for usage on Windows (@raholler)

  • Improved structure of docs

## v0.1 – October 2018

  • First version with cookiecutter (thanks, @tobiasraabe and @julienschat)

  • All the stuff that accumulated over the years with the help of many. I wish my memory was better so I would be able to list the contributions separately. Thanks, @PKEuS, @philippmuller, @julienschat, @janosg, @tdrerup and many more who provided feedback!