Opened 6 years ago

Closed 5 years ago

#8964 closed defect (implemented)

doc/HACKING is out of date

Reported by: rransom Owned by: rl1987
Priority: Very Low Milestone: Tor: 0.2.6.x-final
Component: Core Tor/Tor Version:
Severity: Keywords: tor-doc
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

(as of commit e7134c2375f3c577ab7dcc20c74c5773d1a5f37d)

Line 43 states that the maint-0.2.1 branch is currently ‘actively developed’. It should not.

Line 54 uses “bug 9999” as a dummy bug number. That ticket will be opened this year.

Line 96 refers to “https://buildbot.vidalia-project.net/one_line_per_build”. I don't believe that that URL is still valid.

The Doxygen formatting details (starting after line 329) are frequently ignored in practice. That's probably a good thing, because fewer developers use Doxygen than jump around in the source using TAGS files and grep and read the comments directly. If you don't agree that abandoning Doxygen is a good idea, make check-spaces should detect and complain about at least gross problems (e.g. characters that should be escaped left unescaped).

The HACKING file does not mention using a TAGS file. (I put “find src/ -name '*.[hc]' |etags -” in my Git post-checkout hook.)

Child Tickets

Change History (9)

comment:1 Changed 6 years ago by rransom

The ‘Patch checklist’ should include “document all new or changed configuration options in the fantastic man page”.

No one reads doc/HACKING, because it's hidden away next to a bunch of obsolete documents. The HACKING file is supposed to be in the root directory of the source distribution, right next to README.

comment:2 Changed 6 years ago by rransom

make check-docs and make check-logs should be documented somewhere (if they still work).

comment:3 Changed 6 years ago by nickm

Milestone: Tor: 0.2.4.x-final
Owner: set to nickm
Status: newaccepted

comment:4 Changed 6 years ago by nickm

Milestone: Tor: 0.2.4.x-finalTor: 0.2.5.x-final

Putting this into 0.2.5 for now: it needs more than cosmetic fixes. More stuff to add includes:

  • how to actually make coverage testing work.
  • how to actually make coverage testing work on OSX.
  • Using perf, oprofile, and that osx tool.
  • how to use trac

comment:5 Changed 6 years ago by nickm

I've done 74a534be15a26cddb8 to clean up the outright errors in 0.2.4, though.

comment:6 Changed 6 years ago by nickm

Keywords: tor-doc added

comment:7 Changed 6 years ago by nickm

Milestone: Tor: 0.2.5.x-finalTor: 0.2.6.x-final

comment:8 Changed 5 years ago by rl1987

Owner: changed from nickm to rl1987

comment:9 Changed 5 years ago by nickm

Resolution: implemented
Status: acceptedclosed

I'm closing this. I've been improving doc/HACKING over the past year and gotten ahead of myself about writing more things.

Note: See TracTickets for help on using tickets.