Merge pull request #750 from ElectionDataAnalysis/issue731-community-guidelines

Issue731 community guidelines

Author: sfsinger19103

CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at https://www.contributor-covenant.org/version/1/0/0/code-of-conduct.html

CONTACT_US.md

@@ -0,0 +1 @@
+Contact [Stephanie Singer](http://symmetrysinger.com/index.php?id=contact). 

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+Please note that electiondata is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). 
+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](https://github.com/ElectionDataAnalysis/electiondata/issues). 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.
+  
+1.  A copy of your working directory, following the model in the [Sample Session](docs/Sample_Session.md). 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`.
+  
+1.  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
+1. installing the indicated version of electiondata
+1. 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.
+1. 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.
+1. Run unit tests to check for broken functionality. See [pytest instructions](docs/Testing_Code_with_pytest.md).
+1. Run python `black` to format your code to our standard.
+1. Push branch to github and issue pull request (PR).
+1. Discuss the pull request.
+1. 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](CONTACT_US.md) for help.
+
+If you're not familiar with git or github, please read a tutorial such as [https://realpython.com/python-git-github-intro/](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.
+
+1.  __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.
+    
+1.  __Documentation__ Any new parameters or a new functions must be documented both in the code and in the [User Guide](docs/User_Guide.md), [Sample Session](docs/Sample_Session.md) and any other relevant documents. If you're adding a new graphical or analytical feature, please add a short example to [Sample Session](docs/Sample_Session.md).
+
+1.  __Tests__ If fixing a bug or adding a new feature to a non-graphical function,
+    please add a [pytest](https://docs.pytest.org) unit test. Document the new test in [pytest instructions](docs/Testing_Code_with_pytest.md).
+
+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.
+

README.md

@@ -1,6 +1,5 @@
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4078/badge)](https://bestpractices.coreinfrastructure.org/projects/4078)
 
-
 # Overview
 This repository provides tools for consolidation and analysis of raw election results from the most reliable sources -- the election agencies themselves. 
  * Consolidation: take as input election results files from a wide variety of sources and load the data into a relational database
@@ -16,35 +15,18 @@ This repository provides tools for consolidation and analysis of raw election re
    * Bar charts
 
 # Target Audience
-This system is intended to be of use to news media, campaigns, election officials, students of politics and elections, and anyone else who is interested in assembling and understanding election results.
-
-# How to Contribute Code
-Please contribute code that works in python 3.9, with the package versions specified in [requirements.txt](requirements.txt). We follow the [black](https://pypi.org/project/black/) format.
-
-# How to Help in Other Ways
-If you have skills to contribute to building the system, we can definitely use your help:
- * Creating visualizations
- * Preparing for intake of specific states' results files
- * Managing collection of data files in real time
- * Writing documentation
- * Merging other data sets of interest (e.g., demographics)
- * Building our open source community
- * What else? Let us know!
- 
-If you are a potential end user -- an election official, political scientist or campaign consultant, for instance -- let us know what you want to from this system.
- 
-If you are interested in contributing, or just staying updated on the progress of this project, please [contact Stephanie Singer](http://symmetrysinger.com/index.php?id=contact). 
+This system is intended to be of use to news media, campaigns, election officials, students of politics and elections, and anyone else who is interested in assembling and understanding election results. If you have ideas for using this system or if you would like to stay updated on the progress of this project, [we'd like to hear from you](CONTACT_US.md). 
 
 # How to use the app
 See [documentation directory](docs), which includes
  * for users
    * [Installation instructions](docs/Installation.md)
    * Instructions for a [sample dataloading session](docs/Sample_Session.md)
    * Detailed [User Guide](docs/User_Guide.md)
- * for developers
-   * [Information about the code](docs/About_the_Code.md)
-   * [Information about the tests](docs/Testing_Code_with_pytest.md)
-   
+ 
+# How to Contribute Code
+See [CONTRIBUTING.MD](CONTRIBUTING.md).
+
 # Contributors
  * [Stephanie Singer](http://campaignscientific.com/), Hatfield School of Government (Portland State University), former Chair, Philadelphia County Board of Elections
  * Janaki Raghuram Srungavarapu, Hatfield School of Government (Portland State University)