Skip to content

Latest commit

 

History

History
175 lines (142 loc) · 5.69 KB

CONTRIBUTING.md

File metadata and controls

175 lines (142 loc) · 5.69 KB

Contributing to the openPMD-viewer

How to contribute

Forking the repository

In order to contribute, please fork the main repository:

  • Click 'Fork' on the page of the main repository, in order to create a personal copy of this repository on your Github account.

  • Clone this copy to your local machine:

git clone [email protected]:<YourUserLogin>/openPMD-viewer.git

Implementing a new feature and adding it to the main repository

  • Switch to the development branch
git checkout dev

and install it

python setup.py install
  • Start a new branch from the development branch, in order to implement a new feature. (Choose a branch name that is representative of the feature that you are implementing, e.g. add-latex-labels or fix-matplotlib-errors)
git checkout -b <NewBranchName>
  • Start coding. When your changes are ready, commit them.
git add <ChangedFiles>
git commit
  • Synchronize your branch with the main repository. (It may have changed while you where implementing local changes.) Resolve merging issues if any, and commit the corresponding changes.
git pull [email protected]:openPMD/openPMD-viewer.git dev

  • Test and check your code:

    • Use pyflakes and pep8 to detect any potential bug, and to ensure that your code complies with some standard style conventions.
    cd openPMD-viewer/
pyflakes opmd_viewer
pep8 --ignore=E201,E202,E122,E127,E128,E131 opmd_viewer
    • Make sure that the tests pass (please install wget and jupyter before running the tests: pip install wget jupyter)
    python setup.py install
python setup.py test

    (Be patient: the test_tutorials.py can take approx. 20 seconds if you already downloaded the example openPMD files that are required in the tutorials. On the other hand, it can take several minutes if you have not previously downloaded these files.)

  • Push the changes to your personal copy on Bitbucket

git push -u origin <NewBranchName>
  • Go on your Github account and create a pull request between your new feature branch and the dev branch of the main repository. Please add some text to the pull request to describe what feature you just implemented and why. Please also make sure that the automated tests (on Github) return no error.

Style and conventions

  • Features that modify or improve the OpenPMDTimeSeries object should be implemented in the opmd_viewer/opempmd_timeseries folder. Features that build upon the OpenPMDTimeSeries object to create domain-specific analysis tools (e.g. laser diagnostics for PIC simulations) should be implemented in the opmd_viewer/addons folder.

  • Document the functions and classes that you write, by using a docstring. List the parameters and describe what the functions return, as in this example:

    

    • 



def get_data( dset, i_slice=None, pos_slice=None ) :
"""
Extract the data from a (possibly constant) dataset
Slice the data according to the parameters i_slice and pos_slice


Parameters:
-----------
dset: an h5py.Dataset or h5py.Group (when constant)
    The object from which the data is extracted

i_slice: int, optional
   The index of the slice to be taken

pos_slice: int, optional
   The position at which to slice the array
   When None, no slice is performed

Returns:
--------
An np.ndarray (non-constant dataset) or a single double (constant dataset)
"""
```



Don't use documenting styles like :param:, :return:, or
@param, @return, as they are less readable.


    

  • 

    Lines of code should never have more than 79 characters per line.
    

    • 

  • 

    Names of variables, functions should be lower case (with underscore
if needed: e.g. get_field). Names for classes should use the
CapWords convention (e.g. DataReader). See this page for more details.
    

    • 



Creating a new release


When the code is ready for a new release, please follow these steps:


    

  • Make sure that your local environment is ready for a full release on
PyPI. In particular, you should have pypandoc and twine installed and working. In addition, you should have a registered account on PyPI and test PyPI, and your $HOME should contain a file .pypirc which contains the following text:

    

    • 



[distutils]
index-servers=
pypitest
pypi


[pypitest]
repository = https://testpypi.python.org/pypi
username = 


[pypi]
repository = https://pypi.python.org/pypi
username = 



- Make sure that the release number in `opmd_viewer/__init__.py`
corresponds to the new release, and that the corresponding changes have been
documented in `CHANGELOG.md`.

- Test the PyPI release by uploading the code to [test PyPI](https://testpypi.python.org/pypi):



rm -rf dist
python setup.py sdist bdist_wheel
twine upload dist/* -r pypitest


and then by downloading it from there:



pip install -i https://testpypi.python.org/pypi openPMD-viewer



- If everything works fine, then merge the `dev` version into `master`
and upload it to Github:



git checkout master
git merge dev
git push



- Create a new release through the graphical interface on Github

- Upload the package to [PyPI](https://pypi.python.org/pypi):



rm -rf dist
python setup.py sdist bdist_wheel
twine upload dist/* -r pypi