Many source files have a comment block near the top which includes a list of authors who made changes and a copyright year associated with it. Is the expectation that contributors keep that updated when a change is made?
Git and GitHub are the source of truth for date of change, authorship and reason for change, so it seems duplicate effort to put it in the source file.
I have found this information helpful when trying to determine who is the primary contact for a piece of code. Seeing a short copyright span for the first Developer, a gap and then a lengthier span for a second Developer suggests that the code was debugged then possibly stagnated. Then someone adopted it and gave it love again.
I have inadequate coding skills to contribute directly as a PR. But I’ve shared a couple hacks with developers as proofs of concept. Some have corrected my code, others written a more conforming and efficient routine. Then they’ve released updates to the community.
One said he wasn’t working on that code any longer. So I continued to use my hack and shared the change publicly.
@emyoulation Your reasoning for why change history is useful and important is absolutely correct.
Since Gramps uses Git and GitHub, this is essentially built-in with commits and commit messages, without the inconsistent and often forgotten effort of manually adding a line to the header block of a source file. Developers and non-developers alike can look at the history of a file using GitHub’s web interface to see the history easily.
For example, to see the history of one of the most recently committed files in addons-source, addons-source/Form/form_us.xml, one can easily click on the “History” link on the page to see a full history of commits with details about who made changes and when. GitHub also provides an annotated view of a file with per-line history by using “Blame” functionality.
BTW, there’s a learning curve, but it’s not difficult to create PRs so I’d encourage you to give it a try!
One of my concerns with the GitHub tools is the tight data cap of my ISP. I avoid using any synch tools because they might eat up my data.
(I do not use Gramps’ automatic backup for a similar reason. Until the 5.2 update is released, that backup eats drive space like candy.)
That’s a valid point, and one that highlights a major selling point for Git: allowing offline work. No connection to a remote repository unless explicitly requested.
There’s a one-time hit to pull the full repo down, but even when fetching changes it compresses data. After that only incremental changes are transferred over the wire. Your favorite development tools can be used to search available history from your local drive.
No. These lines are not duplicated.
If someone wants to include the source(s) in another project, the authors will continue to exist in the other project.
By looking at recent git commit history of source files (ignoring .po files) and comparing to the copyright block in the files, I came to the conclusion that attribution within the source files is only partly and incompletely duplicated and not nearly as accurate as the history captured in git.
Giving credit to original authors when copying code is the right thing to do, but I suspect relying on the header block of source files is not the best way.
However, not everything passes through GitHub. At least, not immediately.
So the manual redundancy in the header is a reasonable policy.
Not everyone adds their names to the sources. I.e. If I fix a source file by changing a single line, I don’t add my name to the source, but I should.
Remember: Git is the reference for the history of all changes in the project, not source file changes even if you think so.
As I said before, If you only rely on git, you lose these information if you copy a source file in another project.
Gentlemen, let me summarize:
From the responses so far there is, I believe, recognition that attribution in the header block in source files doesn’t reflect the actual attribution history. If there is a need to track it for any specific purpose, looking up history in source control would be needed to verify it. Yet there appears to be an expectation that when source files are copied from this project to other projects, the attribution in the source will suffice as provenance.
There is no documentation in the guidelines (please share if it is) that says developers should or should not modify the header block. Since there doesn’t seem to be support for calling it out as redundant, the practice will remain as-is.
The question that started this thread has been addressed. Thanks for your input.
From File Header Procedure:
Additional contributors shall add their names and respective years of contribution in the copyright statement if they make changes to the file in the source repository.
@emyoulation Thank you for digging up the link to that wiki - in readings of developer pages I had not come across that yet. It clearly states copyright should be updated by authors, so that again helps answer the question that started this thread.
There’s room to simplify this mundane maintenance work (based on reading questions on this on stackoverflow and various web pages), but copyright is a legal issue and I’m not qualified so I’m happy to leave this here.
This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.