19 Oct
2005
19 Oct
'05
12:18 a.m.
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(a)reactos.org)
* David Welch (welch(a)cwcom.net)
*/
Which is exactly what the kernel uses right now.
Best regards,
Alex Ionescu