Tobias Dammers
On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:
...
I believe this should be a separate, self-contained document; we should not overload the New Contributors' Guide with this information, nor should it be scattered across the rest of the documentation (though more pages should exist to go into full detail on each of those points). The New Contributors' Guide should, however, follow these practices and thus document them by example. E.g., the tutorial should include a step where you squash your commits and add suitable comments. Likewise, the NOTE: convention can be introduced simply by walking through the steps as part of the tutorial.
Sounds like we are largely in agreement. Let's start on this after the Trac migration is finished.
On a completely unrelated note, I was thinking that it may be feasible and desirable to hack up a quick broken-links check for the wiki, possibly even as part of the migration script (which has to extract wiki links anyway as it goes, and also visits every wiki page at some point, so maintaining a list of links and then crossing off the ones that exist shouldn't be a huge effort). Armed with such a list, we could then semi-automatically deal with broken links and redirects as part of a cleanup sweep. I'll have to give redirects a bit more thought in this context though.
I was going to recommend we rather just use something off-the-shelf to avoid reinventing the wheel. I use linkchecker [1] elsewhere and it works quite well. I believe you can use its -W flag to catch non-existent wiki pages (which won't return a 404). Of course, if it's easier to do this as part of the migration script then that is also fine. Cheers, - Ben