Codify code copyright conventions and guidelines

Description

raised the point that we seem to have no written guidelines for dealing with copyright dates in the headers of our source code. It's been part of institutional memory, but we need to capture it somewhere, and the official developer guide seems the right place.

Briefly, here's the deal.

Every source code file in our code bases (whether it's for OpenNMS or another project) should have a comment block at the top which includes copyright information, followed by a license portion. The copyright portion looks like this for a Java source file that is part of the main OpenNMS code base:

 

The two lines containing copyright dates are the focus of this issue.

The first line is specific to the file at hand. The second line applies to the code base as a larger work. One or both lines may need updating any time a developer makes changes to a file. For purposes of identification in the matrix below, I'll assign identifiers [in brackets] to the four years as follows:

Here's an attempt at a matrix illustrating what should change in various scenarios. It assumes that the developer is updating the file in the year 2022 (Gregorian calendar).

 

Scenario description

Year A

Year B

Year C

Year D

Adding a new file to the OpenNMS code base

2022

(empty)

1999

2022

Updating an existing file to the OpenNMS code base, if that file was added in 2004

2004

2022

1999

2022

Adding a new file to a code base created the same year

2022

(empty)

2022

(empty)

Updating an existing file in a code base created the same year

2022

(empty)

2022

(empty)

If Year B or Year D is empty, its companion year (A or C) should not be followed by a dash.

I hope this is enough to make a start. Please tag me with any questions!

 

Acceptance / Success Criteria

  • Developer guide contains a section / subsection on code copyright and license blocks, organized alongside other portions that deal with code standards

  • Guidelines for creating new files and updating existing ones are clearly articulated so that a novice developer can apply them

  • Probably good to have a short blurb about why this seemingly trivial thing actually matters, particularly in open-source code bases; sources to mine could include opensource.org or sfconservancy.org.

Lucidchart Diagrams

Activity

Show:

Bonnie Robinson May 12, 2023 at 1:04 PM

Reopening, as I forgot to add the topic to the TOC.

PR:

Bonnie Robinson May 11, 2023 at 2:47 PM

Bonnie Robinson June 20, 2022 at 6:28 PM

we could move this to the docs backlog and Emily or I could update the docs, with Ben reviewing. Not clear if Ben is working on this currently.

Benjamin Reed February 1, 2022 at 7:14 PM

Also part of this should be making sure the process of doing releases includes updating the display footer copyright in the UI to the current year.

Fixed

Details

Assignee

Reporter

HB Grooming Date

HB Backlog Status

Docs Needed

Yes

Doc Backlog Status

Doc Backlog Grooming Date

Story Points

Original estimate

Time tracking

No time logged4h remaining

Components

Sprint

Affects versions

Priority

PagerDuty

Created January 14, 2022 at 4:02 PM
Updated May 12, 2023 at 1:54 PM
Resolved May 12, 2023 at 1:54 PM