Developer Documentation

We could use help with a number of ongoing issues. If you’d like to help, check the issue tree as well as our requests for pull requests.

If you’ve decided to make a pull request, here is an outline of the development workflow that we have successfully adopted.

Setting up

Fork the repository to your own account (i.e. github user).

Clone or pull your forked repository locally. If you are doing it for the first time:

git clone https://github.com/<your-user-name>/pyglmnet

Or if you have already cloned the repository:

git pull origin master

Setup a remote to point to the main upstream repository.

git remote add upstream https://github.com/glm-tools/pyglmnet
git remote -v

You should see this:

upstream        https://github.com/glm-tools/pyglmnet.git (fetch)
upstream        https://github.com/glm-tools/pyglmnet.git (push)
origin        http://github.com/<your-user-name>/pyglmnet.git (fetch)
origin        http://github.com/<your-user-name>/pyglmnet.git (push)

Before you start developing a feature, make sure that your local master is up to date. This can save you from a lot of merge conflicts later.

git checkout master
git pull upstream master

In case your own fork is behind the main repo, update your fork:

git push origin master

Once you are done with these housekeeping steps, you are ready to start developing.

Develop

Make sure you develop each feature on a new branch:

git checkout -b feat

Develop your changes, and once you are satisfied we need to do a couple of things before adding and committing them.

First if it is a major feature, consider writing a test. You can do this by editing tests/test_pyglmnet.py.

Second, once you have written your tests, run them locally. Install pytest and pytest-cov:

pip install pytest pytest-cov

py.test --cov=pyglmnet tests/

If you don’t see error messages, go ahead and test with a pep8 style checker. We use flake8. Install flake8:

pip install flake8

flake8 --count pyglmnet

If you don’t see any errors, you are good to add and commit.

Add all the files changed and commit them with a short and meaningful message. We recommend one commit per conceptual change since it helps us keep track of what happened more easily.

Note: If you are making changes to the documentation, you will see a number of new files built when you locally build the documentation including the folders: _build, auto_examples, generated, modules, and tutorials. DO NOT add or commit any of these! Only add and commit the files you manually changed (typically .rst or .py files). Once a pull request is made and merged, we will build the documentation to be hosted separately (see below).

Once committed, push your local branch to a branch in your fork.

git push origin feat:feat

Make pull request

From the feat branch of your fork: https://github.com/<your-user-name>/pyglmnet you can create a pull request on to the main repo. Give the PR a meaningful name. We recommend prefixing it with a [WIP] if the feature is being built. If you think it is ready to merge, prefix with [MRG].

If it’s a complicated feature that can evolve better with feedback, we highly recommend making the PR when it’s a work in progress (WIP). In the PR message box, it’s typically good to associate it with an issue (.e.g. “address #253”) in addition to concisely describing the most salient changes made.

Once your PR is made, the tests will run. If there are errors, they will be reported on the PR’s page.

Major PRs are followed by a process of peer review by one of the maintainers commenting on the code and suggesting changes.

For making changes to the PR, make changes to your local feat branch and push to your fork’s feat branch just as you did before making the PR. Your new commits will be automatically associated with the PR and tested.

Sometimes you may make tiny formatting changes that are not worth retesting with our continuous integration systems. For these changes, include a [ci skip] prefix in your commit message. However, use this trick sparingly!

After all suggested changes are resolved, add your name to the whats_new page in the appropriate section. This should be the last commit in the PR before it can be merged.

Once the PR is merged, you can optionally delete the feat branch both locally and on your fork.

Build documentation

The following should be installed in order to build the documentation.

• sphinx

• sphinx-gallery

• pillow

• numpydoc

• matplotlib

Shortcut:

pip install sphinx sphinx-gallery pillow numpydoc matplotlib

We use sphinx to generate documentation page. To build the documentation pages locally, run:

make html

All static files will be built in _build/html/ where you can open them using the web browser.

To remove the built files from your local repository, run:

make clean

To push built documentation page to gh-pages, simply run:

make install