Skip to content

Instantly share code, notes, and snippets.

@bsavitzky

bsavitzky/contributing_to_py4DSTEM.md

Last active June 29, 2023 18:43
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save bsavitzky/8b1ee4c1244814940e7cff4500535dba to your computer and use it in GitHub Desktop.
Save bsavitzky/8b1ee4c1244814940e7cff4500535dba to your computer and use it in GitHub Desktop.
Download ZIP
Contributing to py4DSTEM
Raw
contributing_to_py4DSTEM.md

Notes on contributing to py4DSTEM

This document discusses contributing to the py4DSTEM repository (https://github.com/py4dstem/py4DSTEM).

Branch model

If you're interested in contributing to py4DSTEM, please fork the repository! Fork from the dev branch (currently the default). The master branch is intended as release code, while dev is for ongoing development. Once your edits are ready, submit a pull request back in to the dev branch of the central repo.

Dev environment

This is how I'm presently setting up and working with my dev environment for this project.

With anaconda installed, run

conda create -n py4dstem_dev
conda activate py4dstem_dev

Next, navigate to the directory where you want to put the project, and type

git clone your_fork_url.git

where your_fork_url is the url to the fork you created. Navigate into the new py4DSTEM directory which contains the setup.py file, and run

conda install pip
pip install -e .

where the -e option installs the package in 'editable' mode, so that changes within this project directory will be reflected in py4DSTEM imports from Python interpreters within this environment.

Create a new branch, and make any edits. To merge back in to the main repository, submit a pull request (to the dev branch, which will be set as default) to github.com/py4dstem/py4DSTEM.

Sample code

Sample code lives in the top level direcetory called sample_code. All sample code should use only publically available sample data. Sample data currently lives here.

To add a sample file, either as a .py or a .ipynb, please include the following information in a comment at the top of the file:

  • A short summary of what the file does, and breakdown of the steps to complete this task.
  • Data: include what the data is, appropriate attribution (both who collected it and, if appropriate, what publication(s) it appears in), and a link to where the data can be downloaded.
  • Version info: when was the file last updated, and which version of py4DSTEM did it use?

To add a .ipynb sample file, please additionally clear the cell outputs. A few ways to do this include:

  • In jupyter, click on 'kernel' and then select 'Restart & Clear Outputs'.
  • With the file, call it sample.ipynb, in the sample_code directory, run the nbpublish script with the command ./nbpublish.sh sample.ipynb. The first time you do this you may need to set permissions on your machine to allow nbpublish to execute (chmod 755 nbpublish.sh)

The reason we're clearing outputs before publishing sample notebooks is to prevent our git history from getting clogged with the output plots, which are stored in notebooks as big, ugly binary blobs. The reason for the nbpublish.sh script (rather than just always manually clearing outputs) is because in the near future we plan to additionally automate saving and publically hosting a version of the file with all the outputs, without making our git history terrible.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment