Version numbers and history
1. Version numbers and history
Your package is looking really great now. In this lesson, we'll look at a few small changes you can make to polish it off before your next release.2. Final files
In the last lesson you saw that cookiecutter created these two new files, contributing and history.3. CONTRIBUTING.md
The contributing file is either a markdown or reStructured-text file. This is your call out to other developers for help, and is the first place another developer will look if they are interested in assisting with your package. It is up to you what information you choose to include in this file. You might ask potential developers to join a mailing list, or to email you, or how they can get involved via Github. The standard contributing file which cookiecutter creates, is a great place to start, but you can change it if you'd like to send out a different message to potential collaborators.4. HISTORY.md
The history file is really important for your users. In chapter two, we said that a package's history file is used to figure out which versions of a package will work with your package. There are different terms for this file, you might hear it being called the history, change-log or release notes, but they are all the same thing. The history file will tell your users the important things that have changed between the previous and new releases. This allows them to figure out which versions of your package they should use.5. HISTORY.md
The history file is also a markdown or restructured text file. There is no official guide on how to structure this file, but best practices would look something like this. There should be a heading for each version of your package released, and subheadings for ...6. HISTORY.md
existing parts of the package that have been improved,7. HISTORY.md
for new parts of the package that have been added,8. HISTORY.md
for bug fixes,9. HISTORY.md
and for deprecation warnings, which tell the users when the package has been changed in a way which might break their code that uses it. Under each of these headings there are bullet points telling the users the important updates that have happened. Not all updates will be included here, just the ones which might affect your users.10. HISTORY.md rendered
When rendered the file looks like this.11. Version number
When you make changes, and are ready to make a new release, you will need to increase the version number. Only one copy of the package can be associated with each version number. So PyPI won't let you upload a copy with a version number you have used before. There are two places in the package where you must update the version number. The setup-dot-py file and the top level init-dot-py file.12. The package version number
The version number in the setup file is used by pip and PyPI. The version number in the init file is included for the user, and it is best-practices to include this. It allows them to print and use the package version.13. bumpversion
These version numbers can be updated simultaneously using the simple bump-version tool. This tool is used from the terminal and will search through your package and increase the version number in appropriate places. You simply need to navigate to the top of your package and run bump-version with the argument major, minor or patch, and it will increase the major, minor or patch number.14. Let's practice!
That's it for these extra files, let's practice!Create Your Free Account
or
By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.