Merge pull request py4dstem#580 from alex-rakowski/contributors_guide

adding contributors guidelines

Former-commit-id: 12c7c02

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders 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, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTORS.md

@@ -0,0 +1,126 @@
+## py4DSTEM Contributor Guidelines
+
+**Welcome to the py4DSTEM project!**
+
+We are grateful for your interest in contributing to py4DSTEM, an open-source Python library for 4D-STEM data analysis. Your contributions will help us make py4DSTEM a more powerful and versatile tool for the scientific community.
+
+This document outlines the guidelines and expectations for contributors to the py4DSTEM project. Please read it carefully before making any contributions.
+
+### Contribution Types
+
+There are many ways to contribute to py4DSTEM, including:
+
+* **Reporting bugs:** If you encounter a bug in py4DSTEM, please file a bug report on GitHub. Be sure to provide as much detail as possible about the bug, including steps to reproduce it.
+
+* **Submitting feature requests:** If you have a suggestion for a new feature for py4DSTEM, please submit a feature request on GitHub. Describe the feature in detail and explain how it would benefit users.
+
+* **Improving documentation:** py4DSTEM's documentation is always in need of improvement. If you have suggestions for improving the documentation, please submit a pull request or open an issue on GitHub.
+
+* **Developing new code:** If you are a developer, you can contribute to py4DSTEM by writing new code. Please follow the coding guidelines below.
+
+### Coding Guidelines
+
+* **Code style:** py4DSTEM uses the black code formatter and flake8 linter. All code must pass these checks without error before it can be merged. We suggest using `pre-commit` to help ensure any code commited follows these practices, checkout the [setting up developer environment section below](#install). We also try to abide by PEP8 coding style guide where possible.
+
+* **Documentation:** All code should be well-documented, and use Numpy style docstrings. Use docstrings to document functions and classes, add comments to explain complex code both blocks and individual lines, and use informative variable names.
+
+* **Testing:** Ideally all new code should be accompanied by tests using pyTest framework; at the least we require examples of old and new behaviour caused by the PR. For bug fixes this can be a block of code which currently fails and works with the proposed changes. For new workflows or extensive feature additions, please also include a Jupyter notebook demonstrating the changes for an entire workflow i.e. from loading the input data to visualizing and saving any processed results. 
+
+* **Dependencies:** New dependencies represent a significant change to the package, and any PRs which add new dependencies will require discussion and agreement from the development team. If a new dependency is required, please prioritize adding dependencies that are actively maintained, have permissive installation requirements, and are accessible through both pip and conda.
+
+### Pull Requests
+
+When submitting a pull request, please:
+
+* **Open a corresponding issue:** Before submitting a pull request, open an issue to discuss your changes and get feedback.
+
+* **Write a clear and concise pull request description:** The pull request description should clearly explain the changes you made and why they are necessary.
+
+* **Follow the coding guidelines:** Make sure your code follows the coding guidelines outlined above.
+
+* **Add tests:** If your pull request includes new code, please add unit tests.
+
+* **Address reviewer feedback:** Respond promptly to reviewer feedback and make changes as needed.
+
+### Code Review
+
+All pull requests will be reviewed by project maintainers before they are merged. The maintainers will provide feedback on the code and may ask for changes. Please be respectful of the maintainers' feedback and make changes as needed.
+
+### Code of Conduct
+
+py4DSTEM is committed to providing a welcoming and inclusive environment for all contributors. Please read and follow the py4DSTEM Code of Conduct.
+
+### Acknowledgments
+
+We are grateful to all of the contributors who have made py4DSTEM possible. Your contributions are invaluable to the scientific community.
+
+Thank you for your interest in contributing to py4DSTEM! We look forward to seeing your contributions.
+
+
+### Setting up the Developer Environment
+<a id='install'></a>
+
+1. **Fork the Git repository:** Go to the py4DSTEM GitHub repository and click the "Fork" button. This will create your own copy of the repository on your GitHub account.
+
+2. **Clone the forked repository:** Open your terminal and clone your forked repository to your local machine. This will create a local copy of your fork of the repository on your computer's filesystem. Use the following command, replacing `<your-github-username>` with your GitHub username and <path> with the the directory where you'd like to copy the py4DSTEM repository onto your filesystem:
+
+    ```bash
+    cd <path>
+    git clone https://github.com/<your-github-username>/py4DSTEM.git
+    ```
+**_extra tips_:** Github has an excellent [tutorial](https://docs.github.com/en/get-started/quickstart/fork-a-repo) you can follow to learn more about for steps one and two.
+
+3. **Create a new branch:** Create a new branch for your development work. This will silo any edits you make to the new branch, allowing you to work and make edits to your working branch without affecting the main branch of the repository. Use the following command, replacing `<branch-name>` with a name for your branch.  Please use an informative name describing the purpose of the branch, e.g. `<fixing-virtual-image-bug>`:
+
+   ```bash
+   git checkout -b <branch-name>
+   ```
+
+4. **Create an anaconda environment:** Environments are useful for a number of reasons. They create an isolated computing environment for each project or task, making it easy to reproduce results, manage dependencies, and collaborate with others. There are a number of different ways to use environments, including anaconda, pipenv, virtualenv - we recommend using [anaconda](https://docs.anaconda.com/free/anaconda/install/index.html) for environment management, where you can create a new environment with:
+
+   ```bash
+   conda create -n py4dstem-dev python=3.10
+   ```
+
+You can then enter that environment using:
+
+   ```bash
+   conda activate py4dstem-dev
+   ```
+
+
+5. **Install py4DSTEM in editable mode:** Navigate to the cloned repository directory and install py4DSTEM in editable mode. This will allow you to make changes to the code and test them without having to reinstall the library. Use the following command:
+
+   ```bash
+   conda activate py4dstem-dev
+   pip install -e .
+   pip install flake8 black   # install linter and autoformatter
+   ```
+
+You can now make changes to the code and test them using your favorite Python IDE or editor.
+
+6.  **_(Optional)_ - Using `pre-commit`**: `pre-commit` streamlines code formatting and linting. Essentially it runs black (an autoformatter) and flake8 (a linter) whenever a new commit is attempted on all staged files, and only allows the commit to proceed if they both pass. To use pre-commit, run:
+
+    ```bash
+    conda activate py4dstem-dev
+    pip install pre-commit
+    cd <path-to-your-fork-of-the-py4DSTEM-git-repo>   # go to your py4DSTEM repo
+    pre-commit install
+    ```
+
+This will setup pre-commit to work on this repo by creating/changing a file in .git/hooks/pre-commit, which tells `pre-commit` to automatically run flake8 and black when you try to commit code.  It won't affect any other repos.
+
+**_extra tips_:** 
+
+```bash
+# You can call pre commit manually at any time without committing
+pre-commit run # will check any staged files 
+pre-commit run -a # will run on all files in repo
+
+# you can bypass the hook and commit files without the checks 
+# (this isn't best practice and should be avoided, but there are times it can be useful)
+
+git add file # stage file as usual 
+git commit -m "you commit message" --no-verify # commit without running checks
+git push # push to repo. 
+```

README.md

@@ -11,6 +11,7 @@ Additional information:
 - [Installation instructions](#install)
 - [The py4DSTEM documentation pages](https://py4dstem.readthedocs.io/en/latest/index.html).
 - [Tutorials and example code](https://github.com/py4dstem/py4DSTEM_tutorials)
+- [Want to get involved?](#Contributing)
 - [Our open access py4DSTEM publication in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927621000477) describing this project and demonstrating a variety of applications.
 - [Our open access 4D-STEM review in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927619000497) describing this project and demonstrating a variety of applications.
 
@@ -181,16 +182,18 @@ Links to the data used in each notebook are provided in the intro cell of each n
 
 
 # More information
+<a id='Contributing'></a>
 
-## Documentation
+## Contributing Guide 
+We are grateful for your interest in contributing to py4DSTEM. There are many ways to contribute to py4DSTEM, including Reporting bugs, Submitting feature requests, Improving documentation and Developing new code
 
-Our documentation pages are [available here](https://py4dstem.readthedocs.io/en/latest/index.html).
+For more information checkout our [Contributors Guide](CONTRIBUTORS.md)
 
 
+## Documentation
 
-## For contributors
+Our documentation pages are [available here](https://py4dstem.readthedocs.io/en/latest/index.html).
 
-Please see [here](https://gist.github.com/bsavitzky/8b1ee4c1244814940e7cff4500535dba).
 
 
 ## Scientific papers which use **py4DSTEM**