Hello, Ok here are some proposed ground rules for the audit. Mostly thanks to Art and Alex. We are still open for debate on this
0. Everyone needs commit all documentation you have reverse enginered something so that someone else can reimplement it. Filip has some nice docs at
http://www.volny.cz/xnavara/doc_trash/
There is stuff I posted on the Wiki and Bugzilla. Can someone make a api-documentation module in svn and commit all this stuff to there?
1. A function is deemed to have been implemented in a non-clean manner if
- "unknown" arguments given values - functions for which there is NO DOCUMENTATION - functions with no test cases available either in ReactOS or somewhere on the internet - functions with undocumented magic numbers - functions with excessive gotos
NO DOCUMENTATION means it cannot be found on MSDN, Google, sysinternals, osronline, any book published by Microsoft Press or any other publication.
2. The following does not count - functions of 5 or less lines of code - functions for which every basic unit corresponds to a clause in the official documentation - functions which mimic those implemented in other libraries and that work similarly
3. Even if the function body is not clean, the prototype can remain.
-- Steven Edwards - ReactOS and Wine developer
"There is one thing stronger than all the armies in the world, and that is an idea whose time has come." - Victor Hugo
It is a good idea, but I have an idea. Why don't we use the dirty code we find to write documentation for the related function, and have someone else re-impliment it using that documentation?
Steven Edwards wrote:
Hello, Ok here are some proposed ground rules for the audit. Mostly thanks to Art and Alex. We are still open for debate on this
- Everyone needs commit all documentation you have reverse enginered
something so that someone else can reimplement it. Filip has some nice docs at
http://www.volny.cz/xnavara/doc_trash/
There is stuff I posted on the Wiki and Bugzilla. Can someone make a api-documentation module in svn and commit all this stuff to there?
- A function is deemed to have been implemented in a non-clean manner if
- "unknown" arguments given values
- functions for which there is NO DOCUMENTATION
- functions with no test cases available either in ReactOS or
somewhere on the internet
- functions with undocumented magic numbers
- functions with excessive gotos
NO DOCUMENTATION means it cannot be found on MSDN, Google, sysinternals, osronline, any book published by Microsoft Press or any other publication.
- The following does not count
- functions of 5 or less lines of code
- functions for which every basic unit corresponds to a clause in the
official documentation
- functions which mimic those implemented in other libraries and that
work similarly
- Even if the function body is not clean, the prototype can remain.
-- Steven Edwards - ReactOS and Wine developer
"There is one thing stronger than all the armies in the world, and that is an idea whose time has come." - Victor Hugo
Ros-dev mailing list Ros-dev@reactos.org http://www.reactos.org/mailman/listinfo/ros-dev
On 1/28/06, Steven Edwards winehacker@gmail.com wrote:
Hello, Ok here are some proposed ground rules for the audit. Mostly thanks to Art and Alex. We are still open for debate on this
...
- A function is deemed to have been implemented in a non-clean manner if
- functions for which there is NO DOCUMENTATION
I think this condition isn't always evidence of a non-clean implementation of a function. A developer might have written tests for a function and not committed them back to ReactOS. This could be rewritten as:
"If a function has NO DOCUMENTATION and no test cases exist either in ReactOS or elsewhere, then test cases must be submitted to ReactOS."
- functions with excessive gotos
This case is similar to the documentation case in that it's not direct evidence of a non-clean implementation. I frequently use gotos for releasing many resources in error cases as a way of factoring code. A better wording would be:
"Functions with excessive gotos should be marked for further inspection."
-- James Hawkins
On Sat, 28 Jan 2006 01:21:22 -0600 James Hawkins truiken@gmail.com wrote:
On 1/28/06, Steven Edwards winehacker@gmail.com wrote:
Hello, Ok here are some proposed ground rules for the audit. Mostly thanks to Art and Alex. We are still open for debate on this
...
- A function is deemed to have been implemented in a non-clean manner if
- functions for which there is NO DOCUMENTATION
I think this condition isn't always evidence of a non-clean implementation of a function. A developer might have written tests for a function and not committed them back to ReactOS. This could be rewritten as:
"If a function has NO DOCUMENTATION and no test cases exist either in ReactOS or elsewhere, then test cases must be submitted to ReactOS."
Actually, that appears 4 lines later in the original.
- functions with excessive gotos
This case is similar to the documentation case in that it's not direct evidence of a non-clean implementation. I frequently use gotos for releasing many resources in error cases as a way of factoring code. A better wording would be:
"Functions with excessive gotos should be marked for further inspection."
-- James Hawkins
Nobody's saying 'oh noes ... we must toss all code with gotos'. These are metrics for functions that we must consider as needing more than cursory examination. I was trying to set some boundaries for clearly in and clearly out that can be measured in a somewhat objective way.
To me, using more than two or three goto targets per function is excessive. Goto targets for cleanup and generic error handling are pretty common in C code, but I believe that code which uses more than a handful of gotos should at least be examined in detail.
On 1/28/06, art yerkes ayerkes@speakeasy.net wrote:
Nobody's saying 'oh noes ... we must toss all code with gotos'. These are metrics for functions that we must consider as needing more than cursory examination. I was trying to set some boundaries for clearly in and clearly out that can be measured in a somewhat objective way.
I'm not a developer on the ReactOS project, so I only see what's on the mailing list. My comments were based on Steven's original statement:
"A function is deemed to have been implemented in a non-clean manner if..."
which led me to believe that any functions matching the conditions that followed would be deemed non-clean and removed. I don't have a problem with the removal of non-clean code, but seeing as how this is a draft and still up for debate, I threw in my opinion about two cases that weren't clear enough.
To me, using more than two or three goto targets per function is excessive. Goto targets for cleanup and generic error handling are pretty common in C code, but I believe that code which uses more than a handful of gotos should at least be examined in detail.
Then we are in agreement.
-- James Hawkins
Steven Edwards wrote:
Hello, Ok here are some proposed ground rules for the audit. Mostly thanks to Art and Alex. We are still open for debate on this
- Everyone needs commit all documentation you have reverse enginered
something so that someone else can reimplement it. Filip has some nice docs at
http://www.volny.cz/xnavara/doc_trash/
There is stuff I posted on the Wiki and Bugzilla. Can someone make a api-documentation module in svn and commit all this stuff to there?
- A function is deemed to have been implemented in a non-clean manner if
- "unknown" arguments given values
I remember Ros being 80% unknown, lol!
- functions for which there is NO DOCUMENTATION
- functions with no test cases available either in ReactOS or
somewhere on the internet
- functions with undocumented magic numbers
- functions with excessive gotos
NO DOCUMENTATION means it cannot be found on MSDN, Google, sysinternals, osronline, any book published by Microsoft Press or any other publication.
osronline ddk is offline. We have a books list in the svn in credits.
- The following does not count
- functions of 5 or less lines of code
- functions for which every basic unit corresponds to a clause in the
official documentation
- functions which mimic those implemented in other libraries and that
work similarly
- Even if the function body is not clean, the prototype can remain.
Looks fairly good so far, James
So, disassembling something, working out how it works and writing an english language document of that code for someone else (who hasnt seen the details of the existing MS implementation) to implement is ok or not? Does that count as clean-room enough?
-----Original Message----- From: ros-dev-bounces@reactos.org [mailto:ros-dev-bounces@reactos.org] On Behalf Of Steven Edwards Sent: 28. januar 2006 07:34 To: ros-dev@reactos.org Subject: [ros-dev] Propose standards for the audit
- Even if the function body is not clean, the prototype can remain.
Unless the function is not required to achieve our goal of ReactOS being compatible with Windows-based applications and drivers.
Casper
From: Steven Edwards
Hello, Ok here are some proposed ground rules for the audit. Mostly thanks to Art and Alex. We are still open for debate on this
I'm ok with those ground rules.
Can we fast-track some stuff we couldn't possibly have reverse-engineered? I've already taken the liberty of doing that with rbuild. I'll make a list of components which I think are suitable candidates for fast-tracking and send that later today.
GvG
Can we fast-track some stuff we couldn't possibly have reverse-engineered? I've already taken the liberty of doing that with rbuild. I'll make a list of components which I think are suitable candidates for fast-tracking and send that later today.
GvG
I think we should track this here:
http://www.reactos.org/wiki/index.php/Audit
Casper
From: Casper Hornstrup
I'll make a list of components which I think are suitable candidates for fast-tracking and send that later today.
GvG
I think we should track this here:
Yes, found that page right after I pressed "Send"... I'll use that page and tag the items with "F:" (for fast-track). If anyone disagrees with the classification, we can discuss it here, if in a few days there are no objections we can start moving the stuff over.
How are we going to keep track of the audit results? An audit is not very useful without an audit trail. My proposal is to add a "doc" property to appropriate directories in the code tree and use that to document how the code there was audited. This "doc" property could contain e.g. a short note like "rbuild was developed specifically for ReactOS, there is no non-free code from which it could have been reverse engineered" or it could point to a document stored elsewhere in svn providing more detail. I'm proposing "doc" as the name for the property and not "audit", "rev-eng" or something like that to keep it generic and set that property as the standard for future code development too.
How do we determine if someone is qualified or not to do an audit of a component? I did some work on freeldr, does that make me qualified 'cause I know what I'm talking about or am I not qualified because I'm not independent?
GvG
Yes, found that page right after I pressed "Send"... I'll use that page and tag the items with "F:" (for fast-track). If anyone disagrees with the classification, we can discuss it here, if in a few days there are no objections we can start moving the stuff over.
How are we going to keep track of the audit results? An audit is not very useful without an audit trail. My proposal is to add a "doc" property to appropriate directories in the code tree and use that to document how the code there was audited. This "doc" property could contain e.g. a short note like "rbuild was developed specifically for ReactOS, there is no non-free code from which it could have been reverse engineered" or it could point to a document stored elsewhere in svn providing more detail. I'm proposing "doc" as the name for the property and not "audit", "rev-eng" or something like that to keep it generic and set that property as the standard for future code development too.
Sounds good. There is a convention to prefix property names so it should be ros:doc.
How do we determine if someone is qualified or not to do an audit of a component? I did some work on freeldr, does that make me qualified 'cause I know what I'm talking about or am I not qualified because I'm not independent?
GvG
There was talk of two developers auditing the same code. I would trust people to follow the guidelines and thus say you are qualified to audit freeloader because 'you know what you are talking about' ;-)
Casper
Hi,
On 1/28/06, Casper Hornstrup ch@eudicon.com wrote:
There was talk of two developers auditing the same code. I would trust people to follow the guidelines and thus say you are qualified to audit freeloader because 'you know what you are talking about' ;-)
I am fine with fast tracking code we know not to be reversed. Freeldr seems good according to Alex, Ge, Art and everyone else that has ever messed with it. I think it can be merged back. Its going to depend on the DDK and I would like to take this chance to see if we can fix the w32api SDK/DDK. Right now the w32api DDK is a convultued cluster-fu*k. The DDK part depends on the SDK part. We need to remove that dependancy to make it more Windows compatible.
-- Steven Edwards - ReactOS and Wine developer
"There is one thing stronger than all the armies in the world, and that is an idea whose time has come." - Victor Hugo
-----Original Message----- From: ros-dev-bounces@reactos.org [mailto:ros-dev-bounces@reactos.org] On Behalf Of Steven Edwards Sent: 28. januar 2006 07:34 To: ros-dev@reactos.org Subject: [ros-dev] Propose standards for the audit
I'd like something like the following in the IP policy:
"If an API or a particular behaviour of an API which is part of the Windows(R) operating system is not publicly documented by Microsoft, then the API or the particular behaviour of the API Must only be implemented in ReactOS if there is documentation of published software which depend on the API or the particular behaviour of the API, and which is not only distributed with the Windows(R) operating system. The documentation must be available in the repository."
My reason for this is that any deviation which ReactOS has from Windows will increase our chances of winning a lawsuit.
Casper
-
art yerkes -
Casper Hornstrup -
Ge van Geldorp -
James Hawkins -
James Tabor -
Jerry -
Jonathan Wilson -
Steven Edwards