Propose standards for the audit

[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

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

[Jerry]

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
>
> 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
>
> _______________________________________________
> Ros-dev mailing list
> Ros-dev(a)reactos.org
> http://www.reactos.org/mailman/listinfo/ros-dev
>
>   
>

[James Hawkins]

On 1/28/06, Steven Edwards <winehacker(a)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
>  
...
>   1. 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

[art yerkes]

On Sat, 28 Jan 2006 01:21:22 -0600
James Hawkins <truiken(a)gmail.com> wrote:

>   On 1/28/06, Steven Edwards
> <winehacker(a)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
> >  
>  ...
> >   1. 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.
-- 
Here's a simple experiment. Stand on a train track between two
locomotives which are pushing on you with equal force in opposite
directions. You will exhibit no net motion. None the less, you may
soon begin to notice that something important is happening.
-- Robert Stirniman

[James Hawkins]

On 1/28/06, art yerkes <ayerkes(a)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

[James Tabor]

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
>  
>  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 
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.

>   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.
>   
Looks fairly good so far,
James

[Jonathan Wilson]

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?

[Casper Hornstrup]

>   -----Original Message-----
>  From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On
>  Behalf Of Steven Edwards
>  Sent: 28. januar 2006 07:34
>  To: ros-dev(a)reactos.org
>  Subject: [ros-dev] Propose standards for the audit
>  
>  3. 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

[Ge van Geldorp]

>   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

[Casper Hornstrup]

>   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

[Ge van Geldorp]

>   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:
>  
>  http://www.reactos.org/wiki/index.php/Audit 
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

[Casper Hornstrup]

>   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

[Steven Edwards]

Hi,

On 1/28/06, Casper Hornstrup <ch(a)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

[Casper Hornstrup]

>   -----Original Message-----
>  From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On
>  Behalf Of Steven Edwards
>  Sent: 28. januar 2006 07:34
>  To: ros-dev(a)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