This document walks through the changes needed to fix issue #7 (“implement
delete_key in the wrapper”) as well as how to release the code in the
end. To make it easier to follow through with the process, I am starting on
Create the Branch¶
First we need to create a branch off of master that we can implement our changes in. From the command line, this is:
$ git checkout master # make sure we start on master branch $ git checkout -b add-delete-key-functionality
In this case, I already have a test that does most of the work, I just need to factor out a part of the test to use a new utility function and make a new one that works with the wrapper directly instead of the job interface. From the issue, we want to be able to do:
wrapper = RemoteWrapper(hostname=server.hostname, username=username) with wrapper.connect(password=None, public_key_filename=public_key_path): wrapper.delete_key()
The test that I ended up writing is:
@pytest.mark.django_db def test_delete_key(env): from django_remote_submission.remote import RemoteWrapper if pytest.config.getoption('--ci'): pytest.skip('does not work in CI environments') wrapper = RemoteWrapper( hostname=env.server_hostname, username=env.remote_user, port=env.server_port, ) with wrapper.connect(password=env.remote_password): wrapper.delete_key() with pytest.raises(ValueError, message='needs password'): with wrapper.connect(password=None): pass
Ensure that Test Currently Fails¶
Once we have our test, we want to make sure it fails. We can do this in two
ways, either by running the entire test suite or by just running the specific
test. I put the earlier test in the
test/test_tasks.py file, so if your
test belongs somewhere else, then make sure to change the name appropriately.
$ source venv/bin/activate (venv)$ make test # Run all the tests (venv)$ pytest tests/test_tasks.py::test_delete_key # Run one test
Add Necessary Code to Make Test Pass¶
Now we just need to implement the functionality to get the test(s) to pass. In
this case, I had to actually change a few things, but the main part was just
Test Multiple Python Versions¶
Once it works on the main Python version we’re using, we also need to make sure it works with other versions by running:
$ source venv/bin/activate (venv)$ make test-all
Now we need to commit our changes and push to our feature branch so we can get Travis to run our tests. This may need several iterations to get working in case there are weird edge cases. Usually for parts of this library that pertain to actually connecting to a remote host, we’ll need to have the test be skipped if it’s running on continuous integration hosts.
if pytest.config.getoption('--ci'): pytest.skip('does not work in CI environments')
Make Documentation Changes¶
Some changes will need changes to the documentation to be made, whether that’s adding docstrngs to the implemented methods or adding new pages to the documentation index. Once the changes are made, you should rebuild the documentationt o ensure that it is still working, and taking care to keep track of any warnings (such as “this page has not been included anywhere”).
$ make docs
Again, commit and push the latest changes and ensure it’s still working in Travis.
Make Pull Request and Merge¶
Finally, we just need to actually make the pull request. Go to GitHub, select the feature branch, and select “Compare and Pull Request”. In the body of the message, make sure to reference any issues that it fixes. Travis and a few other integrations will add a comment detailing whether the pull request will successfully merge or not, so pay attention to those warnings or errors.
Once everything passes, then merge the pull request and close the relevant issues.
Update HISTORY.rst and bumpversion¶
Now that the feature branch has been merged into master, we need to switch back
to the master branch, update
HISTORY.rst and bump the version.
$ git checkout master $ git pull origin master $ source venv/bin/activate (venv)$ python -m pip install -r requirements_dev.txt (venv)$ bumpversion patch # or minor or major $ git push origin master $ git push origin --tags
Release to PyPI¶
The last step is to actually release to PyPI. To do this, we first need to make
sure we have a
[distutils] index-servers = pypi [pypi] repository: https://www.python.org/pypi username: YOUR_USERNAME password: YOUR_PASSWORD
And then we just need to make sure we’re on the master branch (now that we’ve merged the feature branch).
(venv)$ make release