{"action":"opened","issue":{"url":"https://api.github.com/repos/jaraco/setuptools_scm/issues/43","labels_url":"https://api.github.com/repos/jaraco/setuptools_scm/issues/43/labels{/name}","comments_url":"https://api.github.com/repos/jaraco/setuptools_scm/issues/43/comments","events_url":"https://api.github.com/repos/jaraco/setuptools_scm/issues/43/events","html_url":"https://github.com/jaraco/setuptools_scm/issues/43","id":92443970,"number":43,"title":"Lack of documentation","user":{"login":"jaraco","id":308610,"avatar_url":"https://avatars.githubusercontent.com/u/308610?v=3","gravatar_id":"","url":"https://api.github.com/users/jaraco","html_url":"https://github.com/jaraco","followers_url":"https://api.github.com/users/jaraco/followers","following_url":"https://api.github.com/users/jaraco/following{/other_user}","gists_url":"https://api.github.com/users/jaraco/gists{/gist_id}","starred_url":"https://api.github.com/users/jaraco/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jaraco/subscriptions","organizations_url":"https://api.github.com/users/jaraco/orgs","repos_url":"https://api.github.com/users/jaraco/repos","events_url":"https://api.github.com/users/jaraco/events{/privacy}","received_events_url":"https://api.github.com/users/jaraco/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-07-01T17:42:51Z","updated_at":"2015-07-01T17:42:51Z","closed_at":"2015-07-01T17:42:51Z","body":"This project is something I am looking for, but I am missing some documentation and/or place to discuss things. Personally, I would like to help with the development and/or documentation, so I share things that I have learned about the problem ``setuptools_scm`` is trying to address:\n\nConnecting SCM with versioning stuff is difficult. There are two major use cases when you want the package to know its version:\n\n* The moment when you release (release-time) the package and \n* the moment when an unsuspecting user installs it without any knowledge of SCM at all.\n\nDuring the release-time, thigs are easy. It is not that difficult to guess the descriptive version string of the package from the SCM. This is mainly because the developer has all tools he needs and the source code is tagged.\n\nHowever, when one releases the package, users that are going to install it don't have the advanced tools and the package should be well-aware of which version it is (a good practice is that package ``foo`` has ``foo.__version__`` attribute that is the semver version string). So, the version has to be somehow injected to the package and the package has to be able to pick it up.\n\nSome quick examples:\n\n* ``numpy`` writes the version they infer from ``git`` to ``numpy/version.py`` at release-time. However, they keep the version number in ``setup.py`` along some boilerplate code.\n* ``setuptools`` maintain a ``setuptools/version.py`` containing a version string in SCM\n* ``matplotlib`` maintains version string in ``lib/matplotlib/__init__.py`` and has relatively convoluted code that extracts it.\n\nGenerally, there are two ways of how to solve this:\n\n1. Store the version string somewhere and introspect it from ``setup.py`` using more or less convoluted code you have to write yourself.\n\n2. Generate the version string during release-time and inject it somehow to the package in a smart way.\nThe cons of this approach is that it is an unusual approach and one can forget to perform the injection step. Having it as a hook of ``setup.py [sb]dist`` would be so much cleaner. \n\n    Also, there would be the ordering problem - first you tag, then you release and the release gets modified ex-post when it gets the right version string. So the package should be tagged afterwards or the part with the version string should not be revision-controled.\n\nNow, let's get to ``setuptools_scm``.\nAFAIK, users will be obliged to get it when they get in touch with package that requires it, which I regard as sub-optimal, but if parts of it get integrated into ``setuptools``, it would dissolve this weakness.\nOn the other hand, it seems to me that it is introspecting ``PKG-INFO``, which I think is the right way to go. In my opinion, generating ``PKG-INFO`` is essentially the injection step and people in charge of their package's ``setup.py`` just have to have good possibilities of getting it out of the file.\n\nSo what would I like to see in this package:\n\n* Better documentation. Everybody needs under-the-hood documentation because of inevitable [leakage of abstractions](http://en.wikipedia.org/wiki/Leaky_abstraction). A tutorial is also a must.\n* Integration of ``PKG-INFO`` parsing to ``setuptools``, a pattern of using ``setuptools_scm`` in a way that end-users don't have to worry about having it installed.\n\n----------------------------------------\n- Bitbucket: https://bitbucket.org/pypa/setuptools_scm/issue/24\n- Originally reported by: Matěj Týč\n- Originally created at: 2015-02-27T14:10:43.625\n"}}