If you’ve decided to make a pull request, here is an outline of the development workflow that we have successfully adopted.
Fork the repository to your own account (e.g. user).
Clone or pull your forked repository locally. If you are doing it for the first time:
git clone https://github.com/user/pyglmnet
Or if you have an already existing local clone:
git pull origin master
Setup a remote to point to the main repository.
git remote add main https://github.com/glm-tools/pyglmnet git remote -v
You should see this:
main https://github.com/glm-tools/pyglmnet.git (fetch) main https://github.com/glm-tools/pyglmnet.git (push) origin http://github.com/user/pyglmnet.git (fetch) origin http://github.com/user/pyglmnet.git (push)
Before you start developing a feature, make sure that your local master is up to date. This will save you a lot of merge conflicts later.
git checkout master git pull main 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.
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. We test with nosetests:
nosetests . --with-coverage
If you don’t see error messages, go ahead and test with a pep8 style checker. We use 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 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/user/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 core developers 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, the PR can be merged.
Once the PR is merged, you can optionally delete the feat branch both locally and on your fork.
The following should be installed in order to build the documentation.
pip install sphinx sphinx-gallery pillow numpydoc matplotlib
We use sphinx to generate documentation page. To build the documentation pages locally, run:
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:
To push built documentation page to gh-pages, simply run: