Difference between revisions of "User:Furey/References to source code"
(first draft.) |
(Redo organization.) |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | + | {{tocright}} | |
| − | + | = Timeline = | |
2003: [[NetHack 3.4.3]] released. | 2003: [[NetHack 3.4.3]] released. | ||
| Line 25: | Line 25: | ||
These were fine as long as there was only one THE source. | These were fine as long as there was only one THE source. | ||
| − | + | = The new multiversion world = | |
After the release of [[NetHack 3.6.0]], things changed. Some of the methods for making source code references grew a new parameter to specify the version. The new parameter had to be optional, and it had to default to [[NetHack 3.4.3]] so that legacy references would continue to work. This scheme relies on editors conscientiously choosing the right source version when referring to source code. | After the release of [[NetHack 3.6.0]], things changed. Some of the methods for making source code references grew a new parameter to specify the version. The new parameter had to be optional, and it had to default to [[NetHack 3.4.3]] so that legacy references would continue to work. This scheme relies on editors conscientiously choosing the right source version when referring to source code. | ||
| Line 31: | Line 31: | ||
This scheme has not worked. | This scheme has not worked. | ||
| − | === Case in point: [[allmain.c]] | + | == Case in point: [[acid hound]] == |
| + | |||
| + | Contains two calls to Template:monster. The first call defines "acid hound pup" with refline=580. The second call defines "acid hound' with refline=622. The two reflines resolve to https://nethackwiki.com/wiki/Source:NetHack_3.6.1/src/monst.c , which of course does not have any acid hounds. Line 580 is inside the definition of "large mimic", and line 622 is inside the definition of "hobgoblin". | ||
| + | |||
| + | This is likely a problem for many monster definitions in variants. | ||
| + | |||
| + | == Case in point: [[allmain.c]] == | ||
Consider [[Source:NetHack 3.4.3/src/allmain.c]] itself. The second sentence of the article reads: | Consider [[Source:NetHack 3.4.3/src/allmain.c]] itself. The second sentence of the article reads: | ||
| Line 38: | Line 44: | ||
Wrong. [[allmain.c]] used to redirect to [[Source:NetHack 3.4.3/src/allmain.c]], but in December 2015, someone changed the redirect to [[Source:NetHack 3.6.1/src/allmain.c]]. This was a quiet change, and it broke callers. It also means anyone using [[allmain.c]] today has to remember that this is a 3.6.1 file. Is it going to be a 3.7.0 file in 2026? Nobody knows. | Wrong. [[allmain.c]] used to redirect to [[Source:NetHack 3.4.3/src/allmain.c]], but in December 2015, someone changed the redirect to [[Source:NetHack 3.6.1/src/allmain.c]]. This was a quiet change, and it broke callers. It also means anyone using [[allmain.c]] today has to remember that this is a 3.6.1 file. Is it going to be a 3.7.0 file in 2026? Nobody knows. | ||
| − | + | == Case in point: [[speed]] == | |
Consider https://nethackwiki.com/index.php?title=Speed&oldid=171493 , a historical version from right before I fixed it. Here are three references from the article: | Consider https://nethackwiki.com/index.php?title=Speed&oldid=171493 , a historical version from right before I fixed it. Here are three references from the article: | ||
| Line 47: | Line 53: | ||
When I followed these line numbers, the results were nonsense. The problem is that the unversioned refsrc defaults to NetHack 3.4.3, but the editor who wrote the article provided line numbers from NetHack 3.6.7. This problem is endemic in our articles. | When I followed these line numbers, the results were nonsense. The problem is that the unversioned refsrc defaults to NetHack 3.4.3, but the editor who wrote the article provided line numbers from NetHack 3.6.7. This problem is endemic in our articles. | ||
| − | + | == Case in point: Template:monster == | |
Consider [[titan]]. The infobox for monster data shows a source code reference of [[monst.c#line1438]]. This resolves to NetHack 3.6.1, and in the 3.6.1 version of src/monst.c, line 1438 is 5 lines away from the actual line that defines MON("titan", ...). A five line version skew is not much but it will get a lot worse when NetHack 3.7.0 releases. | Consider [[titan]]. The infobox for monster data shows a source code reference of [[monst.c#line1438]]. This resolves to NetHack 3.6.1, and in the 3.6.1 version of src/monst.c, line 1438 is 5 lines away from the actual line that defines MON("titan", ...). A five line version skew is not much but it will get a lot worse when NetHack 3.7.0 releases. | ||
| − | + | = Statistics = | |
Some of our templates track unversioned usage. Statistics as of June 21, 2024. | Some of our templates track unversioned usage. Statistics as of June 21, 2024. | ||
| Line 67: | Line 73: | ||
89 members (0 subcategories, 0 files) - 00:17, 27 January 2020 | 89 members (0 subcategories, 0 files) - 00:17, 27 January 2020 | ||
| − | + | = Proposal = | |
In one sentence: | In one sentence: | ||
Latest revision as of 23:40, 22 June 2024
Timeline
2003: NetHack 3.4.3 released.
2005: NetHackWiki created.
2015: NetHack 3.6.0 released.
During the time between 2005 and 2015, there was one vanilla source code, plus SLASH'EM 0.0.7E7F2 source code, plus an abortive attempt at SLASH'EM 0.0.7E7F3 source code (only 5 files were uploaded). So there was one source, THE source.
Editors wrote many different features to reference THE source:
- Source:NetHack 3.4.3/src/allmain.c
- Allmain.c
- Source:Allmain.c
- Source:Ref/moveloop
- {{refsrc|allmain.c}}
- {{refsrc|src/allmain.c|nnn}}
- {{sourcecode}}
- {{function}}
- {{reffunc}}
- ... and probably more ...
These were fine as long as there was only one THE source.
The new multiversion world
After the release of NetHack 3.6.0, things changed. Some of the methods for making source code references grew a new parameter to specify the version. The new parameter had to be optional, and it had to default to NetHack 3.4.3 so that legacy references would continue to work. This scheme relies on editors conscientiously choosing the right source version when referring to source code.
This scheme has not worked.
Case in point: acid hound
Contains two calls to Template:monster. The first call defines "acid hound pup" with refline=580. The second call defines "acid hound' with refline=622. The two reflines resolve to https://nethackwiki.com/wiki/Source:NetHack_3.6.1/src/monst.c , which of course does not have any acid hounds. Line 580 is inside the definition of "large mimic", and line 622 is inside the definition of "hobgoblin".
This is likely a problem for many monster definitions in variants.
Case in point: allmain.c
Consider Source:NetHack 3.4.3/src/allmain.c itself. The second sentence of the article reads: To link to a particular line, write [[allmain.c#line123]], for example.
Wrong. allmain.c used to redirect to Source:NetHack 3.4.3/src/allmain.c, but in December 2015, someone changed the redirect to Source:NetHack 3.6.1/src/allmain.c. This was a quiet change, and it broke callers. It also means anyone using allmain.c today has to remember that this is a 3.6.1 file. Is it going to be a 3.7.0 file in 2026? Nobody knows.
Case in point: speed
Consider https://nethackwiki.com/index.php?title=Speed&oldid=171493 , a historical version from right before I fixed it. Here are three references from the article:
- {{refsrc|allmain.c|137}}
- {{refsrc|allmain.c|147}}
- {{refsrc|allmain.c|119}}
When I followed these line numbers, the results were nonsense. The problem is that the unversioned refsrc defaults to NetHack 3.4.3, but the editor who wrote the article provided line numbers from NetHack 3.6.7. This problem is endemic in our articles.
Case in point: Template:monster
Consider titan. The infobox for monster data shows a source code reference of monst.c#line1438. This resolves to NetHack 3.6.1, and in the 3.6.1 version of src/monst.c, line 1438 is 5 lines away from the actual line that defines MON("titan", ...). A five line version skew is not much but it will get a lot worse when NetHack 3.7.0 releases.
Statistics
Some of our templates track unversioned usage. Statistics as of June 21, 2024.
https://nethackwiki.com/index.php?search=unversioned
Page title matches Category:Pages with unversioned Sourcecode templates 119 members (0 subcategories, 0 files) - 00:19, 27 January 2020 Category:Pages with unversioned Refsrc templates 258 members (0 subcategories, 0 files) - 00:19, 27 January 2020 Category:Pages with unversioned Reffunc templates 85 members (0 subcategories, 0 files) - 00:18, 27 January 2020 Category:Pages with unversioned Function templates 89 members (0 subcategories, 0 files) - 00:17, 27 January 2020
Proposal
In one sentence:
Every reference to source code must explicitly specify a version number.
Yeah, yeah, that's nice. But it has a lot of implications.
- Hundreds of existing articles must be fixed.
- We must change our templates to give errors if a version number is not specified.
- Relying on people to choose to specify a version number has not worked.
- Popular templates such as monster and object will need all of their callers changed.
This will be a hard sell, because someone will propose a default that is convenient for them, predicated on the assumption that people will follow their rules about how the default behaves. And then other people will produce mis-matched references like the examples cited above. At that point there will be enormous numbers of worthless source references in our article base, which taint the trustworthiness of all the source references. That is where we are today.
