Re: [jgrapht-users] JGraphT file headers

[John S. <js...@gm...>]

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 <js...@gm...> 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
>
>