JGraphT file headers

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

JGraphT file headers

John Sichi
Administrator
As part of the 1.0 release, we're planning to streamline the boilerplate at the top of all of the source files.

The current template is quite verbose, which has a few disadvantages:

* there's extra work involved in filling it out when creating each new file, which is a burden for new contributors (and their reviewers), and often leads to mistakes due to copy-and-paste

* it's easy for inconsistencies to creep in over time when contributors forget to maintain the header (if you compare the change summary at the top of files with their git history, you'll find many of these)

So here's the proposed new template:

/*
 * (C) Copyright 2008-2016, by Elliot Alderson and Contributors.
 *
 * JGraphT : a free Java graph-theory library
 *
 * This program and the accompanying materials are dual-licensed under
 * either
 *
 * (a) the terms of the GNU Lesser General Public License version 2.1
 * as published by the Free Software Foundation, or (at your option) any
 * later version.
 *
 * or (per the licensee's choosing)
 *
 * (b) the terms of the Eclipse Public License v1.0 as published by
 * the Eclipse Foundation.
 */

We'll be preserving the file-level copyright notice, eliminating the existing project-level copyright notice which currently appears at the top of each file.  The start year will be the year the file was created, while the end year will be 2016 (various reformattings in this release are going to involve touching every file).  Going forward, for new files, contributors will be expected to set the start year correctly, and reviewers should enforce this.

The author name (Elliot Alderson in this example) will be the person who created the file.  One of the advantages of the old verbose header was that it tried to be careful to give credit to everyone who worked on the file over time.  So, with the new format, when contributors make non-trivial changes to existing files, they should feel free to add themselves as an explicit author to the file-level copyright, e.g.

 * (C) Copyright 2008-2016, by Elliot Alderson, Dominique DiPierro, and Contributors.

github will always have the full change history for every file, so "and Contributors" covers the rest.

 The rest of the header can be copy/pasted verbatim.

The HISTORY.md file will remain an important source of detailed attribution information (especially since for the svn portion of the project's history, many contributions were submitted via emailed patches instead of via source control).  Going forward, we'll be careful to keep this up and also increase the verbosity where appropriate in order to compensate for the streamlined headers.  And if you are a historical contributor who would like to request more specific credit in HISTORY.md, please feel free to submit a pull request against that file and we'll take a look.

If you have suggestions, questions, or concerns about any of this, please reply here!

tl;dr:  less is more


------------------------------------------------------------------------------

_______________________________________________
jgrapht-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jgrapht-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: JGraphT file headers

John Sichi
Administrator
The new header format has now been applied to the entire codebase.  (Thanks Joris for whipping up the script for this!)

If you're a contributor, and you find a problem in the way the script edited a file, please submit a pull request to correct it and we'll take a look.

And for new pull requests, please be sure to follow the new format.

On Sun, Sep 4, 2016 at 5:50 PM, John Sichi <[hidden email]> wrote:
As part of the 1.0 release, we're planning to streamline the boilerplate at the top of all of the source files.

The current template is quite verbose, which has a few disadvantages:

* there's extra work involved in filling it out when creating each new file, which is a burden for new contributors (and their reviewers), and often leads to mistakes due to copy-and-paste

* it's easy for inconsistencies to creep in over time when contributors forget to maintain the header (if you compare the change summary at the top of files with their git history, you'll find many of these)

So here's the proposed new template:

/*
 * (C) Copyright 2008-2016, by Elliot Alderson and Contributors.
 *
 * JGraphT : a free Java graph-theory library
 *
 * This program and the accompanying materials are dual-licensed under
 * either
 *
 * (a) the terms of the GNU Lesser General Public License version 2.1
 * as published by the Free Software Foundation, or (at your option) any
 * later version.
 *
 * or (per the licensee's choosing)
 *
 * (b) the terms of the Eclipse Public License v1.0 as published by
 * the Eclipse Foundation.
 */

We'll be preserving the file-level copyright notice, eliminating the existing project-level copyright notice which currently appears at the top of each file.  The start year will be the year the file was created, while the end year will be 2016 (various reformattings in this release are going to involve touching every file).  Going forward, for new files, contributors will be expected to set the start year correctly, and reviewers should enforce this.

The author name (Elliot Alderson in this example) will be the person who created the file.  One of the advantages of the old verbose header was that it tried to be careful to give credit to everyone who worked on the file over time.  So, with the new format, when contributors make non-trivial changes to existing files, they should feel free to add themselves as an explicit author to the file-level copyright, e.g.

 * (C) Copyright 2008-2016, by Elliot Alderson, Dominique DiPierro, and Contributors.

github will always have the full change history for every file, so "and Contributors" covers the rest.

 The rest of the header can be copy/pasted verbatim.

The HISTORY.md file will remain an important source of detailed attribution information (especially since for the svn portion of the project's history, many contributions were submitted via emailed patches instead of via source control).  Going forward, we'll be careful to keep this up and also increase the verbosity where appropriate in order to compensate for the streamlined headers.  And if you are a historical contributor who would like to request more specific credit in HISTORY.md, please feel free to submit a pull request against that file and we'll take a look.

If you have suggestions, questions, or concerns about any of this, please reply here!

tl;dr:  less is more



------------------------------------------------------------------------------
What NetFlow Analyzer can do for you? Monitors network bandwidth and traffic
patterns at an interface-level. Reveals which users, apps, and protocols are
consuming the most bandwidth. Provides multi-vendor support for NetFlow,
J-Flow, sFlow and other flows. Make informed decisions using capacity
planning reports. http://sdm.link/zohodev2dev
_______________________________________________
jgrapht-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jgrapht-users
Loading...