[Enhancement] CFF and bump2version (#1)

[kevinmatthes]

Summary

This Pull Request introduces support for CFF and bump2version.

CFF

About

CFF is a standard in order to cite software. Repositories equipped with a valid CITATION.cff can be cited in papers and theses just like books and articles. Also when recommending a project to others, CFF will come in handy. The citation meta data can be converted to APA and BibTeX entries for a list of references.

One can not only maintain a list of contributors as many open source projects do but also give a list of consulted references and further readings for the interested, respectively.

This CITATION.cff comes with a validation Action in order to ensure its correctness. The initial meta data is derived from the repository. The CITATION.cff is valid according to schema version 1.2.0 (latest). The Action is known to succeed in about 10 seconds, the whole run takes approximately 30 seconds.

References

Druskat, S., Spaaks, J. H., Chue Hong, N., Haines, R., Baker, J., Bliven, S., Willighagen, E., Pérez-Suárez, D., & Konovalov, A. (2021). Citation File Format (Version 1.2.0) [Computer software]. https://doi.org/10.5281/zenodo.5171937

bump2version

About

bump2version is a free and open source Python 3 CLI which helps to auto-increment the version number of a software. It is licensed MIT and available via the Python Package Index. The behaviour of the application is controlled by a configuration file named .bumpversion.cfg and stored in the repository root. This configuration file is self-maintaining. Whenever one needs to increment the version of the project prior to a new release, bump2version will update all registered files as well as its own configuration file ("self-maintaining").

bump2version also offers auto-committing and auto-tagging the new version. This would enhance the current release build step in the makefile. The messages are set to the conventions derived from the recent Git History. Auto-committing and auto-tagging is invoked by calling the application as follows:

bump2version --commit --tag patch # update to 0.17.1
bump2version --commit --tag minor # update to 0.18.0
bump2version --commit --tag major # update to 1.0.0

Without the --commit and --tag options, the respective functionalities are not invoked. To enable them permanently, the corresponding settings can be added to the configuration file.

[bumpversion]
commit = True
tag = True

Please consult the official README for further information on configuration as well as practical examples.

References

Verkerk, C., & The bump2version Community. (2020). bump2version (Version 1.0.2-dev) [Computer software]. https://github.com/c4urself/bump2version

Conclusion

This Pull Request is intended to enhance the documentation (CFF features) as well as the maintenance workflow (bump2version setup) of this project. Since the suggested changes are initial setups of the respective technologies for further discussion, I did not create a corresponding changelog entry, yet. As soon as both the citation meta data as well as the bump2version configuration are agreed on, I am going to submit the changelog entry, as well.

[kevinmatthes]

bump2version will complain if there are uncommitted changes in the workspace. The command line option to override this complaint is --allow-dirty. This complaint shall prevent a loss of progress.

For the integration into the build routine, I recommend to place the version increment before the compilation of the changelog with Scriv. In this build routine, the version increment instruction (bump) invokes the fetching of the pending changelog entries (scriv) where the version is a hard coded magic number. Due to the previous version increment, the new version number will be entered instead of the old one automatically since the build routine is tracked by bump2version. (Please note that the build routine is based upon just instead of make.)

[nedbat]

Thanks, I'll have to look into bump2version. I haven't automated version increments yet, and am usually slow to automate things. I'm not sure I understand the value of CFF? Is software really cited often enough for this to be worth it?

[kevinmatthes]

In my opinion, yes, software is cited often enough.

My use case for citing software is to name it in papers as a software utility as there might be conferences requiring doing so. Furthermore, some applications might become an integral part of the publication such that citing them will become mandatory. One approach of citing software is to refer to its manual which will work for projects like Asymptote. But sometimes, this approach is not sufficient as the manual is written by a documentation team and not by the original developers, for instance. This happened me with OpenSCAD. Then, finding a rather uniform way of citing the software becomes difficult. CFF offers an easy solution to this problem.

CFF is furthermore explicitly designed to be able to redirect the citation object. This is a common use case if, for a paper, there is also a reference implementation available. The researchers then often prefer to have the reference implementation cited with the citation object of the latest paper, see FINUFFT. To redirect the citation object, one just needs to specify a preferred-citation with the object to be cited instead.

And finally, when recommending a software to others, being able to give a citation object -- such as in this issue's description -- helps to summarise the most important information about a tool. Due to the GitHub integration of CFF, there will be a corresponding blob on the project's main page: "Cite this repository". Copying the citation data from there is usually a bit faster and definitely more accurate than only giving the project's URL.

[kevinmatthes]

There is also another use case for citing software apart from referencing it in papers: citing software in manuals. Tools like Doxygen allow for a LaTeX reference list post-processing (BibTeX). Projects which make use of Scriv could then name it as a reference in their manuals by relying on the CITATION.cff.

[nedbat]

I'm sorry, but my attention is limited. I don't see CITATION.cff files in common projects that are much more likely to be cited than scriv (for example, requests, black, numpy). I see that pandas has one, but scriv seems far too niche to be at the leading edge of this. I'm closing this for now.