Include versioneer.py to have automatic version update in setup.py

KikeM commented 4 years ago

Is your feature request related to a problem? I have realized that you update manually the version number. This could create problems and mismatches.

Describe the solution you'd like Include versioneer in the project.

It is a great tool, since when you haven't explicitly created a new tag, it indicates from the most recent tag you are working from, the number of commits you are ahead and the commit hash. When a clean tag is created, it's caught and correctly set.

I can implement this feature if you want to.

peterdsharpe commented 4 years ago

Hi @KikeM ,

Sounds very interesting, thanks for bringing this up! I'm currently working on other features of the code right now, but if you have the time to implement this, I'd be more than happy to merge a pull request!

Thanks, Peter

KikeM commented 4 years ago

See https://github.com/peterdsharpe/AeroSandbox/pull/26.

peterdsharpe commented 4 years ago

Hey @KikeM ,

Sorry - I'm having a bit of trouble learning to use versioneer. I only started using Python and Git last summer, so I'm still pretty new to all this (I just learned what a git tag is today!).

Would it be possible for you to walk me through the steps of releasing a new version (both here on GitHub and through PyPI)?

Sorry if this is basic - I really appreciate it! Thanks!

KikeM commented 4 years ago

Sure! Damn, you are doing a pretty good job already if you have only learned since last summer.

For what comes next, this is my understanding of git, perhaps a professional IT developer has more things to add or understands things differently.

Understanding commits

Okey, so here is how your commits look like.

[Kike@MacBook-Pro-de-Enrique AeroSandbox]$git log -n 5 
commit 215417a52f4702be1d296ab2d2ed0b4c1ddd8ca0 (HEAD -> feature/versioneer, origin/feature/versioneer)
Author: Enrique Millan Valbuena <enrique.millanvalbuena@gmail.com>
Date:   Sun Mar 15 23:32:57 2020 +0100

    ENH: included versioneer for automatic version control.

commit 189d8902fe336b9cdb6d8a4e783bf9cca66374fa (origin/hotfix/xfoil_installation, hotfix/xfoil_installation)
Author: Enrique Millan Valbuena <enrique.millanvalbuena@gmail.com>
Date:   Sun Mar 15 23:20:40 2020 +0100

    ENH: removed xfoil as a mandatory dependency, cleaned-up requirements.txt file so versions are fixed.

commit 854aee40c526455c1e8518a115050921303b336e (master)
Author: peterdsharpe <peterdsharpe@gmail.com>
Date:   Sun Mar 15 15:30:07 2020 -0500

    Update propulsion_propeller.py

commit ec33b6c9cc18935905d4a6b6e8ee5779a746f327
Author: peterdsharpe <peterdsharpe@gmail.com>
Date:   Sun Mar 15 13:57:49 2020 -0500

    versioning cleanup; reverting accidental example change

commit 93ca75e3b49dda3b7e1e5b91a16d7c6a2281e01f
Author: peterdsharpe <peterdsharpe@gmail.com>
Date:   Sun Mar 15 13:10:15 2020 -0500

    fixing imports; tests for mass_gearbox

You see how there is a large number next to the keyword commit? That's called a hash number, which identifies uniquely the state of your repository at the time of that commit. This means that you can revert your repository to each commit with that hash number, by using the command

git checkout commit-hash

Ideally you want to do small changes across your commits, so that when things breakup it is easy to rollback to a previous working version. Therefore, for each branch you can end up having many commits. Also, it is healthy to use labels in front of the commits:

ENH: enhancement. You are adding a new feature.
BUG: you are fixing a bug (I never know how to write these commits, either describing the bug or the solution haha).
DOC: you are updating docs.
TST: the commit has to do with unit tests.
CLN: you are refactoring, cleaning up code but not really adding anything new.

and as many as you want! But ideally you want to keep only a handful, so that it is easy to triage in case you need to find where did you introduce a bug (because it will happen :P).

Release

Now, say you have done enough changes, including features, bugs, documenting, etc. You want to make your release. Ideally, you want to carry out the following steps:

Pass your tests (if you have any).
Merge to master.
Create a tag.

Tagging your repo

Creating a tag means that you are going to assign a name to a commit hash number.

Why would you want to do so? To facilitate developers moving across versions, without having to look for the specific commit number. If I can simply write

git checkout v1.1.1

instead of

git checkout 215417a52f4702be1d296ab2d2ed0b4c1ddd8ca0

you have already done my life so much easier.

So basically, tags allow you to label states of the code in a human-friendly way. To create one, simply checkout to a commit on your repo and write

git tag tag-name

Tags can be deleted, so don't worry about creating one and then changing your mind. Although if it is because you added features, what you want to use then is semantic versioning. Simply put, in the version numbers X.Y.Z you want to increase them this way:

Z: same method headers, inputs and outputs. Running the same lines on different versions of this number never breaks down. This is when you fix bugs, enhance performance, include more examples, better documentation. When you change the insides.
Y: new functionality is introduce, while maintaining backwards compatibility. That is, you add new methods, or new optional arguments to methods. This means that if I write code on version X.Y1.Z and I run this code with library X.Y2.Z it doesn't break down (but it could conversely).
X: different method names, headers, inputs, outputs. Basically, radical changes that do not necessarily account for backwards compatibility.

Verisoneer and semantic versioning

Versioneer takes care of getting the version when you run pip install. What is interesting about it is that it can help you now how far ahead you are from the last clean tag you did.

Say you open a branch from v.1.0.0, called feature/drag_skin. You start working and you make 5 commits. If you were to install that branch locally, you would get version v.1.0.0+5.gHASH-NUMBER. If you additionally install it locally and you have uncommitted changes it will add the dirty keyword to remind you.

This means that if you are tagging, you don't need to worry about changing the version number in the setup.py file. But it needs to come with a good use of git tag. If you follow semantic versioning, you are tagging quite often, but that allows your code to be traceable, which you might find helpful in the future.

KikeM commented 4 years ago

I'll have a look to the PyPi release steps and inform you, I've never released there myself.

peterdsharpe / AeroSandbox