Skip to content

Latest commit

 

History

History
73 lines (52 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

73 lines (52 loc) · 4.15 KB
Raw

Please note that electiondata is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Contributing to electiondata development

Report a Problem

To report a problem, file an issue on GitHub. When filing an issue, the most important thing is to include a minimal reproducible example so that we can quickly verify the problem, and then figure out how to fix it. Please include

  1. Link to the exact version of electiondata you are using.

  2. A copy of your working directory, following the model in the Sample Session. Include:

    • a run_time.ini file (Feel free to redact the login information for your local postgres instance.)
    • all subdirectories referenced in the run_time.ini file.
    • If the issue involves loading a particular results data file, be sure to include that file. If possible, avoid submitting large results files -- if your file is precinct-based, for example, see if you can demonstrate the issue with a truncated results file.
    • all error and warnings files placed by the system into the reports_and_plots_dir specified in run_time.ini.

  3. A transcript of the python session, where python is called from the working directory.

You can check you have actually made a reproducible example by:

  1. creating a virtual environment
  2. installing the indicated version of electiondata
  3. if files or folders were moved by the system to the archive directory, move them back to the input directory, removing any timestamps from directory names.
  4. navigating to the working directory, calling python, and producing the behavior in question.

Revise the Code

To contribute a change to electiondata follow these steps:

  1. Create a branch in git and make your changes.
  2. Run unit tests to check for broken functionality. See pytest instructions.
  3. Run python black to format your code to our standard.
  4. Push branch to github and issue pull request (PR).
  5. Discuss the pull request.
  6. Iterate until either we accept the PR or decide that it's not a good fit for electiondata.

Each of these steps are described in more detail below. This might feel overwhelming the first time you get set up, but it gets easier with practice. If you get stuck at any point, feel free to contact us for help.

If you're not familiar with git or github, please read a tutorial such as https://realpython.com/python-git-github-intro/.

Pull requests will be evaluated against this checklist:

  1. Motivation. Your pull request should clearly and concisely motivate the need for change.

  2. Only related changes. Before you submit your pull request, please check to make sure that you haven't accidentally included any unrelated changes. These make it harder to see exactly what's changed, and to evaluate any unexpected side effects.

    Each PR corresponds to a git branch, so if you expect to submit multiple changes make sure to create multiple branches. If you have multiple changes that depend on each other, start with the first one and don't submit any others until the first one has been processed.

  3. Documentation Any new parameters or a new functions must be documented both in the code and in the User Guide, Sample Session and any other relevant documents. If you're adding a new graphical or analytical feature, please add a short example to Sample Session.

  4. Tests If fixing a bug or adding a new feature to a non-graphical function, please add a pytest unit test. Document the new test in pytest instructions.

This seems like a lot of work but don't worry if your pull request isn't perfect. Unless you've submitted a few in the past it's unlikely that your pull request will be accepted as is. All PRs require review and approval from at least one member of the electiondata development team before merge.