Find best way to fit coding convention notes into wiki

The HACKING file is awesome, but it would probably be good to add the coding convention issues to the wiki as well.  It may be easier for new volunteers to find.  I recommend adding a link to the wiki entry to the HACKING file, and adding a link from the HACKING file to the wiki.

I will seek feedback on tor-dev as to the best way to include a link to this page from our other documentation and the front page of the wiki

Also, I categorized this ticket as Company because I think it will help maintain our institutional memory, and I couldn't find another component that seemed to fit better.  If someone has a better way to categorize this please feel free to change the ticket.

added coding component::company convention owner::tomb points::1 priority::medium resolution::wontfix status::closed type::enhancement wiki labels

Fix CodingInC to be a child of CodingForTor

Just copying seems like a poor choice and a guarantee to get out of sync. Instead, we can just link to https://gitweb.torproject.org/tor.git/blob_plain/master:/doc/HACKING or https://gitweb.torproject.org/tor.git/blob/master:/doc/HACKING

Replying to tomb:

The HACKING file is awesome, but it would probably be good to add the coding convention issues to the wiki as well.  It may be easier for new volunteers to find.

Information on the wiki is less likely to be seen (and far less likely to be trusted) by the new volunteers who need to see it than information in Git.

The best way to make the HACKING file more useful is to put it in the root directory of the Tor Git repo (rather than hiding it under doc/ where it is now), and keep it up to date.

Replying to rransom:

Replying to tomb: Information on the wiki is less likely to be seen (and far less likely to be trusted) by the new volunteers who need to see it than information in Git.

The best way to make the HACKING file more useful is to put it in the root directory of the Tor Git repo (rather than hiding it under doc/ where it is now), and keep it up to date.

I do have one question about this, which is that some people may check out some piece of Tor other than tor. For example, my target audience with the R coding conventions may be people who are just checking out metrics, or torperf. What is the best way to help such people find the information? Word of mouth is great, but doesn't scale well. I fortunately found and read HACKING early on, but only because I chose to do a long march through all the files in the main tor repository. I am not sure I would want to expect, for example, an undergrad trying to make a small contribution as a class project to have to do this. Even though I actually read HACKING a few months ago, reading through it today I realize that it answers questions I have recently been asking on the IRC channels. If the information was more easily searchable I might have wasted less of other people's time. Also, I feel kind of dumb asking some of these simple questions, and for some people that feeling might present a barrier to participation.

I note that when I google for "tor coding convention" the only relevant hit is this ticket. I did a non-scientific totally random set of google searches on some of the phrases in the HACKING file and got no relevant hits on the first page of results.

I am not at all suggesting that the wiki is the only or the best way to make this information accessible, but I am willing to spend time implementing whatever people decide is a better solution.

Replying to tomb:

Replying to rransom:

Replying to tomb: Information on the wiki is less likely to be seen (and far less likely to be trusted) by the new volunteers who need to see it than information in Git.

The best way to make the HACKING file more useful is to put it in the root directory of the Tor Git repo (rather than hiding it under doc/ where it is now), and keep it up to date.

I do have one question about this, which is that some people may check out some piece of Tor other than tor. For example, my target audience with the R coding conventions may be people who are just checking out metrics, or torperf. What is the best way to help such people find the information?

Put the information in a file named HACKING in the root directory of the repository to which it is relevant. If you need to have more than one such file, create a directory named HACKING.d in the root directory of the repository, and put your informational files in there.

Word of mouth is great, but doesn't scale well. I fortunately found and read HACKING early on, but only because I chose to do a long march through all the files in the main tor repository. I am not sure I would want to expect, for example, an undergrad trying to make a small contribution as a class project to have to do this.

I didn't see the HACKING file until you filed this ticket, because it was hidden away inside the doc/ directory next to the man pages and a pile of obsolete TODO files. I learned most of Tor's coding conventions by reading the source code for a few minutes.

I note that when I google for "tor coding convention" the only relevant hit is this ticket. I did a non-scientific totally random set of google searches on some of the phrases in the HACKING file and got no relevant hits on the first page of results.

I don't quite understand why anyone would expect Google to turn up useful information about a project's coding conventions, but the solution to this problem is to make Google index the important parts of our Git repositories.

I am not at all suggesting that the wiki is the only or the best way to make this information accessible, but I am willing to spend time implementing whatever people decide is a better solution.

The wiki is a strictly worse place for this information than a HACKING file in its conventional location inside the relevant source code repository. Every developer who works on source code in a repository would have easy access to a copy of the HACKING file at the same time, but reading a 'coding conventions' wiki page would require a good Internet connection.

This ticket is old, and way out of date with most recent conversations on the subject.

Trac:
Resolution: N/A to wontfix
Status: new to closed

closed

changed time estimate to 8h