document original author, contributors, reviewers in easyblocks

[boegel]

We should keep track of original authors, and also contributors and reviewers in each easyblock.

That would help significantly with quality assurance of the easyblocks.

[fgeorgatos]

On Fri, Nov 16, 2012 at 7:38 PM, Kenneth Hoste notifications@github.comwrote:

We should keep track of original authors, and also contributors and reviewers in each easyblock.

That would help significantly with quality assurance of the easyblocks.

+1

Not only this is a good idea also for the easyconfigs, it can serve a few purposes, among them:

• it increases the quality of the blocks/configs since your name(s) is/are now in it
• it is free advertising for the employer of each one of us which reinforces investing in the tool
• it is ensuring the information returns to the individual that understands that piece of code best
• gives the incentive to many more participants to jump in and contribute

In short, this is exactly how it should be!

[fgeorgatos]

Hi folks,

hey, I could help with this issue, since I want to make also own headers consistent throughout;

I see some lengthy headers here and there: https://github.com/hpcugent/easybuild-easyblocks/blob/develop/easybuild/easyblocks/n/neuron.py I guess this is an effect of the guideline visible here: http://www.gnu.org/licenses/gpl-howto.html

Well, I think more concise headers let people provide/get the more interesting information instead and this won't interfere with GPLv2 release status: http://lxr.linux.no/linux+v3.7.3/kernel/fork.c http://lxr.linux.no/linux+v3.7.3/kernel/mutex.c http://lxr.linux.no/linux+v3.7.3/kernel/time.c esp. code author is important in order to pass the stream of questions to the correct person and, often, the context this code relates to so it is understood why it is there at all.

I personally prefer something in the lines of what Jonathan Leffler proposes here: http://stackoverflow.com/questions/134188/what-to-write-in-the-header-comments-of-a-code-file

But again, since I am going to touch your contribs, better you dictate the style.

ps. Hack a reference piece, show me the URL and I'll do the task; I just can't guarantee for v1.1.0 timeline, but it will be done.

cheers, Fotis

[fgeorgatos]

ps. a line "License: GPLv2" will go a long way; the community overall respects the wishes of code authors.

[boegel]

@JensTimmerman Are we obliged to use the full GPLv2 license header in every code file, or can we shorten it significantly as we please? We'll be cleaning up the header to transfer the personal copyright lines into @author lines, so now is the time to maybe significantly shorten those pesky long license header lines.

[boegel]

One suggestion:

License: GPLv2
Copyright: Ghent University (2009-2013)

and then a module docstring like:

"""
EasyBuild support for Armadillo, implemented as an easyblock

@authors: Kenneth Hoste (UGent), Fotis Georgatos (Uni.lu)
"""

[fgeorgatos]

btw. if you find some other python project having the style you think is best, this would be the optimal way to communicate your preference. If that project is already integrated with sphinx/web-code-export , you get bonus points for that ;-)

[fgeorgatos]

fyi. Copying the implementation from https://github.com/turon/git-rcs-keywords I've found a keyword-substitution exploiting header style like the following, which I intend to adopt for the HPCBIOS-related contributions: (and assuming we verify it plays nicely with all the common git workflows):

#  This file is an EasyBuild recipy as per https://github.com/hpcugent/easybuild
#
# Copyright:: Copyright (c) 2012 University of Luxembourg / Luxembourg Centre for Systems Biomedicine
# Author::    Fotis Georgatos <fotis.georgatos@uni.lu>
# License::   MIT/GPL
# $Id: Linux-Kernel-3.6.1.eb | Mon Jan 21 01:35:43 2013 +0100 | Fotis Georgatos  $
#
# This work is part of HPCBIOS project and implements policy:
# 007 - well, "short of"

Caveat: it requires a fresher git version (eb-supplied git one is fine) & some glue mechanism to make it work; on the up-side, most of the glue logic arrives automatically with a "git clone" operation, except for the very final hook which switches it on (ie. the user must knowingly activate it). Also, the information gets truly visible after clean checkout. (somehow, this implementation seems to not get confused with the git hashes, need to investigate the "how" of it)

fyi. the "Author::" is manually put by a human hand, while the one in $Id$ line is the last committer, really. Both ones may have their value to be there.

[fgeorgatos]

I hope you find this information interesting: When I look at github, or even with git blame, the $Id$ remains in its initial form: https://github.com/fgeorgatos/easybuild.experimental/blob/master/users/fgeorgatos/extras/Linux-Kernel-3.6.1.eb This tells to me that the rcs-like keywords remain unexpanded within git storage and they are likely replaced upon checkout only (this makes sense because it can be indeed calculated on the fly).

Notice how close to gets to the code style visible here: http://epydoc.sourceforge.net/api/ -> Package epydoc "source code" (in fact, I think it's actually a bit improved!)

[boegel]

According to http://www.gnu.org/licenses/gpl-howto.html, we need the lengthy header we now have...

[boegel]

This is going to have to wait until v1.2.0 .

We can't postpone v1.1.0 anymore, it's way overdue.

[fgeorgatos]

We still need to proceed with this issue; it's not highly critical but postponing it lets trivialities pile up.

Importantly, it may prove to be a good idea to check how the concept of git-metadata-based filters (see https://github.com/turon/git-rcs-keywords) interacts with epydoc, because we may nicely automate the whole thing and remove the damned human from the workflow (in this case, the human is me). ie. we can enforce absolute consistency between git metadata and epydoc information for all these items of information: $Id$, $Date$, $File$, $Authors$, $Revision$, $Source$ The way this works is described here: """The mechanism used are filters. The smudge filter is run on checkout, and the clean filter is run on commit. The tags are only expanded on the local disk, not in the repository itself."""

It think even Linus would not object to that idea (==the keyword expansion does not mess up with the repo).

[JensTimmerman]

but people who don't run these hooks will only have the tags, and not what needs to be in there?

[fgeorgatos]

Hi Jens,

On Fri, Feb 8, 2013 at 5:07 PM, Jens Timmerman notifications@github.comwrote:

but people who don't run these hooks will only have the tags, and not what needs to be in there?

True.

I was thinking that this could be setup at least on the server that is exporting the documentation online, so there would be a common point of reference for that info; then again, by manually keeping a list in the header you can ensure that there is at least something available for those without the keyword expansion. Anyway, there are pros & cons to each approach, best is to wait to show you how it functions in a hackathon or such, so that you have more info to decide if this makes sense.

cheers, Fotis

[boegel]

I really prefer having the authors in place in the code files themselves, so if code files wander off somewhere, the info is still there. Keeping track of them shouldn't bee too big of an issue, and if someone forgets to add their name, meh, then they don't get credit for their work. ;-) Having a check that makes sure that at least one author is there would be nice though, so there's at least one contact point for all code files.

[JensTimmerman]

So I think we agreed on

"""
EasyBuild support for Armadillo, implemented as an easyblock

@author: Kenneth Hoste (University of Ghent)
@author: Fotis Georgatos (Uni.lu)
"""

[boegel]

Should be fixed for framework by #510

[boegel]

Fixed by #510