[ros-dev] top-level source header

[Alex Ionescu]

Ged wrote:

> Although a standard header was drafted out for the ReactOS source 
> code, few people seem to use it and it doesn't seem to be in the wiki.

Agreed, I will setup a vote on it ASAP.

>
> I would like to get something in the wiki agreed on by everyone which 
> should be included in our source files.
> I think we firstly need have a vote to see if everyone actually wants 
> a standard header, but I put together some info anyway to explain my 
> thoughts
>
>
> As much of the ReactOS code is licensed under the GPL, it can be 
> reused by anyone under the license agreements.
> As the BSD code does, I think a ReactOS copyright notice should be 
> placed in the header to ensure people know where the original code 
> came from. Our current header has no provision for this meaning anyone 
> reading ReactOS code away from the project won't have a return point.
> I was talking this over with Alex, who suggested everyone might not 
> want to give copyright to the foundation. Any suggestions?
>
> Using the existing header, I have drafted a slightly modified version
>
> /*
> 1 * ReactOS <place holder>
> 2 * Copyright (C) 2005 ReactOS Foundation
> 3 *
> 4 * LICENCE:     <place holder>
> 5 * PROJECT:     <place holder>
> 6 * FILE:        <place holder>
> 7 * PURPOSE:     <place holder>
> 8 * PROGRAMMERS: <place holder>
> 9 * REVISIONS:
> 10 *             <place holder>
> 11 *
> */
>
> 1. This is a quick line to state the area which the code was written 
> for. Examples could include:
>       ReactOS Executive
>       ReactOS Win32 Subsystem
>       ReactOS Win32 Applications

Unnecessary, the "PROJECT" line should already state this.

>
> 2. The copyright should detail a date when the copyright was initiated 
> along with the date when it was last modified. For example:
>       1999 - 2004
> The proceeding date should be updated each time a revision is made.

As I've stated, you cannot claim Copyright to the ReactOS foundation 
unless EVERY developer that has touched that file agrees to it. This 
would require significant administrative resources as well as locating 
any previous project members. And that still doesn't guarantee that they 
will all agree to give copyright to the foundation. As it stands, 
copyright belongs to the actual developers that have written the file.

>
> 4. This line should state the licence used and where to find the 
> COPYING file
>
> 5. This line should state what project / binary the code is for. 
> Examples could include:
>       ReactOS ntdll library
>       ReactOS ws2_32 library
>       ReactOS arp utility
>       ReactOS cache manager
>       ReactOS thread scheduler
>
> 6. This line should state the location of the file within the repository
>
> 7. This line should state the purpose of the project / binary the code 
> is intended for
>
> 8. This line should state any programmers whom have worked on the 
> code. The programmer can also choose to add an email address along 
> with their name as a point of contact
>
> 9. This line should list any revisions made to the code. The revisions 
> should include programmers initials, which can be linked to the 
> PROGRAMMERS section, the date the revision was made and a short 
> comment describing the revision. This is not meant for bug fixes and 
> small modifications, but for feature additions or substantial patches

When some of us unofficially discussed the project header, we determined 
it was not a good idea to have a revision entry for 3 simple facts:
1) Waste of space
2) Duplicate information, we have SVN for this
3) Even disregarding the first two reasons, if you look back at when 
this was used, almost no developers actually update the revision field. 
Few of them even upgrade the "programmer" field. A lot of files have 
David Welch in the kernel simply because his original header was copied 
everywhere. Developers which actually worked on the file often don't 
appear at all. Getting people to update the revisions field would be 
even harder. Additionally, it's completely unnecessary since SVN is 
there for that (and this was the original argument that was made against 
it).

>
> I think we should put something in the wiki in relation to this.

Add it to the coding guidelines I guess.

>
> Does anyone have any other suggestions, or modifications to my header.

I suggest something as follows:

/*
 * PROJECT:     ReactOS Kernel
 * LICENSE:     GPL - See COPYING in the top level directory
 * FILE:        ntoskrnl/ex/mutant.c
 * PURPOSE:     section of the kernel
 * PROGRAMMERS: Alex Ionescu (alex at reactos.org)
 *              David Welch (welch at cwcom.net)
 */

Which is exactly what the kernel uses right now.

Best regards,
Alex Ionescu