forked from materialsproject/pymatgen
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
{ADMIN,CONTRIBUTING,LICENSE}.{rst->md} (materialsproject#2738)
* convert ADMIN.rst, CONTRIBUTING.rst, LICENSE.rst to markdown * use inline code for shell commands in readme
- Loading branch information
Showing
7 changed files
with
246 additions
and
284 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,151 @@ | ||
# Introduction | ||
|
||
This documentation provides a guide for pymatgen administrators. The | ||
following assumes you are using miniconda or Anaconda. | ||
|
||
## Releases | ||
|
||
The general procedure to releasing pymatgen comprises the following | ||
steps: | ||
|
||
1. Wait for all unittests to pass on CircleCI. | ||
2. Update and edit change log. | ||
3. Release PyPI versions + doc. | ||
4. Release conda versions. | ||
5. Release Dash documentation. | ||
|
||
## Initial setup | ||
|
||
Install some conda tools first: | ||
|
||
```sh | ||
conda install --yes conda-build anaconda-client | ||
``` | ||
|
||
Pymatgen uses [invoke](http://www.pyinvoke.org/) to automate releases. | ||
You will also need sphinx and doc2dash. Install these using: | ||
|
||
```sh | ||
pip install --upgrade invoke sphinx doc2dash | ||
``` | ||
|
||
Create environment for py38 using conda: | ||
|
||
```sh | ||
conda create --yes -n py38 python=3.8 | ||
``` | ||
|
||
For each env, install some packages using conda followed by dev install | ||
for pymatgen: | ||
|
||
```sh | ||
conda install --yes numpy scipy sympy matplotlib cython | ||
pip install '.[optional]' | ||
pip install invoke sphinx doc2dash | ||
``` | ||
|
||
Add your PyPI username and password and GITHUB_RELEASE_TOKEN into your | ||
environment: | ||
|
||
```sh | ||
export TWINE_USERNAME=PYPIUSERNAME | ||
export TWINE_PASSWORD=PYPIPASSWORD | ||
export GITHUB_RELEASES_TOKEN=TOKEN_YOU_GET_FROM_GITHUB | ||
``` | ||
|
||
You may want to add these to your .bash_profile to avoid having to type | ||
these each time. | ||
|
||
### Machine-specific issues | ||
|
||
The above instructions are general, but there are some known issues that | ||
are machine-specific: | ||
|
||
- Installing lxml via pip required <span | ||
class="title-ref">STATIC_DEPS=true pip install lxml</span> on macOS | ||
10.13. | ||
- It can be useful to <span class="title-ref">pip install --upgrade pip | ||
twine setuptools</span> (this may be necessary if there are | ||
authentication errors when connecting to PyPI). | ||
- You may have to <span class="title-ref">brew install hdf5 | ||
netcdf</span> or similar to be able to pip install the optional | ||
requirement <span class="title-ref">netCDF4</span>. | ||
|
||
## Doing the release | ||
|
||
Ensure appropriate environment variables are set including <span | ||
class="title-ref">DISCOURSE_API_USERNAME</span>, <span | ||
class="title-ref">DISCOURSE_API_KEY</span> and <span | ||
class="title-ref">GITHUB_RELEASES_TOKEN</span>. | ||
|
||
First update the change log. The autogenerated change log is simply a | ||
list of commit messages since the last version. Make sure to edit the | ||
log for brevity and to attribute significant features to appropriate | ||
developers: | ||
|
||
```sh | ||
invoke update-changelog | ||
``` | ||
|
||
Then, do the release with the following sequence of commands (you can | ||
put them in a bash script in your PATH somewhere): | ||
|
||
```sh | ||
invoke release --notest --nodoc | ||
invoke update-doc | ||
python setup.py develop | ||
``` | ||
|
||
Double check that the releases are properly done on Pypi. If you are | ||
releasing on a Mac, you should see a pymatgen.version.tar.gz and two | ||
wheels (Py37 and P). There will be a py37 wheel for Windows that is | ||
generated by Appveyor. | ||
|
||
## Materials.sh | ||
|
||
Fork and clone the | ||
[materials.sh](https://github.com/materialsvirtuallab/materials.sh). | ||
This repo contains the conda skeletons to build the conda versions for | ||
various matsci codes on the Anaconda [matsci | ||
channel](https://anaconda.org/matsci). | ||
|
||
The first time this is run, you may need to <span class="title-ref">pip | ||
install beautifulsoup4</span>. | ||
|
||
If you doing this for the first time, make sure conda-build and | ||
anaconda-client are installed: | ||
|
||
```sh | ||
conda install --yes conda-build anaconda-client | ||
``` | ||
|
||
Update the pymatgen meta.yaml: | ||
|
||
```sh | ||
invoke update-pypi pymatgen | ||
``` | ||
|
||
Build the mac versions manually: | ||
|
||
```sh | ||
invoke build-conda pymatgen | ||
``` | ||
|
||
Commit and push to repo, which will build the Linux and Windows | ||
versions. | ||
|
||
Check that the [matsci channel](https://anaconda.org/matsci) versions | ||
are properly updated. | ||
|
||
## Dash docs | ||
|
||
Fork and clone the [Dash User Contributions | ||
repo](https://github.com/Kapeli/Dash-User-Contributions). | ||
|
||
Generate the offline Dash doc using: | ||
|
||
```sh | ||
invoke contribute-dash | ||
``` | ||
|
||
Create a pull request and submit. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
# Collaborative Github Workflow | ||
|
||
For developers interested in expanding pymatgen for their own purposes, we recommend forking pymatgen directly from the [pymatgen GitHub repo](https://github.com/materialsproject/pymatgen). Here's a typical workflow: | ||
|
||
1. Create a free GitHub account (if you don't already have one) and perform the necessary setup (e.g., install SSH keys etc.). | ||
|
||
2. Fork the pymatgen GitHub repo, i.e., go to the main [pymatgen GitHub repo](https://github.com/materialsproject/pymatgen) and click fork to create a copy of the pymatgen code base on your own Github account. | ||
|
||
3. Install git on your local machine (if you don't already have it). | ||
|
||
4. Clone *your forked repo* to your local machine. You will work mostly with your local repo and only publish changes when they are ready to be merged: | ||
|
||
```sh | ||
git clone [email protected]:YOURNAME/pymatgen | ||
``` | ||
|
||
Note that the entire Github repo is fairly large because of the presence of test files, but these are absolutely necessary for rigorous testing of the code. | ||
|
||
5. It is highly recommended you install all the optional dependencies as well. | ||
|
||
6. Code (see [Coding Guidelines](#coding-guidelines)). Commit early and commit often. Keep your code up to date. You need to add the main repository to the list of your remotes. | ||
|
||
```sh | ||
git remote add upstream git://github.com/materialsproject/pymatgen | ||
``` | ||
|
||
Make sure your repository is clean (no uncommitted changes) and is currently on the master branch. If not, commit or stash any changes and switch to the master. | ||
|
||
```sh | ||
git checkout master | ||
``` | ||
|
||
Then you can pull all the new commits from the main line | ||
|
||
```sh | ||
git pull upstream master | ||
``` | ||
|
||
Remember, pull is a combination of the commands fetch and merge, so there may be merge conflicts to be manually resolved. | ||
|
||
7. Publish your contributions. Assuming that you now have a couple of commits that you would like to contribute to the main repository. Please follow the following steps: | ||
|
||
1. If your change is based on a relatively old state of the main repository, then you should probably bring your repository up-to-date first to see if the change is not creating any merge conflicts. | ||
|
||
2. Check that everything compiles cleanly and passes all tests. The pymatgen repo comes with a complete set of tests for all modules. If you have written new modules or methods, you must write tests for the new code as well (see [Coding Guidelines](#coding-guidelines)). Install and run pytest in your local repo directory and fix all errors before continuing further. | ||
|
||
3. If everything is ok, publish the commits to your github repository. | ||
|
||
```sh | ||
git push origin master | ||
``` | ||
|
||
8. Now that your commit is published, it doesn't mean that it has already been merged into the main repository. You should issue a merge request to pymatgen maintainers. They will pull your commits and run their own tests before releasing. | ||
"Work-in-progress" pull requests are encouraged, especially if this is your first time contributing to pymatgen, and the maintainers will be happy to help or provide code review as necessary. Put "\[WIP\]" in the title of your pull request to indicate it's not ready to be merged. | ||
|
||
## Coding Guidelines | ||
|
||
Given that pymatgen is intended to be long-term code base, we adopt very strict quality control and coding guidelines for all contributions to pymatgen. The following must be satisfied for your contributions to be accepted into pymatgen. | ||
|
||
1. **Unit tests** are required for all new modules and methods. The only way to minimize code regression is to ensure that all code are well-tested. If the maintainer cannot test your code, the contribution will be rejected. | ||
2. **Python PEP 8** [code style](https://www.python.org/dev/peps/pep-0008). We allow a few exceptions when they are well-justified (e.g., Element's atomic number is given a variable name of capital Z, in line with accepted scientific convention), but generally, PEP 8 must be observed. Code style will be automatically checked for all PRs and must pass before any PR is merged. To aid you, you can copy the example pre-commit hook into your .git/hooks directly. This will automatically run `pycodestyle` and other linting services prior to any commits. At the very least, copy pre-commit to .git/hooks/pre-push. | ||
3. **Python 3**. We only support Python 3.8+. | ||
4. **Documentation** required for all modules, classes and methods. In particular, the method doc strings should make clear the arguments expected and the return values. For complex algorithms (e.g., an Ewald summation), a summary of the algorithm should be provided, and preferably with a link to a publication outlining the method in detail. | ||
For the above, if in doubt, please refer to the core classes in pymatgen for examples of what is expected. |
Oops, something went wrong.