Include / Link to How To Contribute wiki page - #1005
Conversation
Created a CONTRIBUTING.rst which GitHub will pick up and included a link to the How To Contribute wiki page there. Also added the same link to the README in the "How To Contribute" section.
|
@singingwolfboy please review |
|
I don't think this has enough content. At the very least, it should:
The wiki page can describe these requirements in more details, but the CONTRIBUTORS file should at least list them. |
|
The problem then is any tweaks have to be replicated across all our repos. |
|
So I deliberately put all content in the wiki so it's in one place that is linked to, not duplicated in every repo. |
|
I see your point, but I still think that the CONTRIBUTING file should have some reasonable content. @nedbat, can you weigh in on this? |
Based on the How To Contribute wiki page (and switched to markdown so it's a simple copy-paste).
|
As discussed on HipChat, I've copied the entire wiki page for just this repo. Lesser-used repos can still just have the link so we don't have to modify 20 repos whenever there's a change. |
|
The "Python Guidelines" and "Javascript Guidelines" links are broken. Also, lines that are >80 characters make me sad. |
|
I'll add my voice to the rising chorus decrying long lines. Word wrap, please! Also, can't we stick with ReST uniformly throughout the repo? |
|
The wiki page the content came from was in Markdown (and didn't have linebreaks). If I translate this to ReST, it will be harder to keep this in sync with the wiki page. (as it is I'm worried people will update in one place and forget to update in the other place) |
|
James, I'm not sure which pages are duplicated between our wiki and the github wiki, but I'd say none of them should be. I see now that I added a bullet to the Python Guidelines internally, and somehow didn't notice the notice at the top of the page about them also being in the github wiki. Is there a reason to keep the internal version? I'd replace it entirely with a pointer to the github wiki. If we want comment, let's just do them ad-hoc the way c2.com does. Not great, but better than duplicated content. |
|
As someone outside your building that tries periodically consults documentation, I'd like all documentation to always be in only the github wiki (or some other publicly editable wiki) and not ever anywhere else, and READMEs in project source code should just have URLs to those public wiki pages. I think all duplication of content is insanity, and I think docs maintained with the source tree drift faster than docs maintained on a public wiki. I think a contributor guidelines page is the perfect place to begin fixing what I call in my head "the documentation problem". Just my $0.02 (github wiki is really impoverished and crummy in a lot of ways, but it has the advantage of autoheating references to issues and commits, and to already being there, so I think it's an acceptable de facto standard) |
|
Alright, I think I'm overruled. Let's make the CONTRIBUTING file just have a link to the wiki, and have done with it. :) |
|
@jrbl I agree we shouldn't duplicated content between two wikis. But docs in the source tree are more likely to be updated, no? When changing code, grep finds me references in the docs but not the wiki. And changes can be branched, merged, reviewed, etc, all the good things we insist on for code changes. Wouldn't we want those for doc changes? |
|
@nedbat Note that what follows issues from the keyboard of a Wiki True Believer who almost had a heart attack the first time he met Ward Cunningham, so take what follows with salt liberally applied wherever it makes sense. My stance on this, as with many things, is probably a bit extremist. I think that that is an appealing line of argument, but IME in the communities I've engaged with in the past, it's untrue in practice. Most people editing code don't bother to edit docs, and if they do, they only edit them in one or a small number of places, rather than globally. ( Obvious corollary: the most useful developer documentation is the pydoc, because it's most likely to be true. ) Also, the barrier to documentation updates is higher with formal introduction of source control. I know that I've been guilty of not updating documentation nits because it wasn't worth the bother to pull a branch, and I suspect everyone else has too. Nits pile up this way. And the overhead for casual newcomers to fix doc problems when the docs are kept in the source repo makes it unlikely they'll ever both to donate fixes, even when they've just been through a painful experience like standing up the stack for the first time. Especially then, probably. Because, effort. The last time I looked, the github wiki was built around gollum, which, IIRC, is powered by a git repository. So it's grepable and you can do forks and branches and so forth with it. Because clearly, you want good tools like these for doing serious documentation revision and update projects. But most interaction between editors and documentation is more ad-hoc than that, so it's also got this (impoverished) web UI to enable (most of the) common wiki functionality to more casual users. To facilitate open-source community building, I feel like lowering friction to casual interaction is a key goal. |
|
Just to throw more fuel on this: I think wikis are fine for developer/ops instructions & faqs. I have a hard time buting an argument of "hard to remeber to edit/update a I think more important would be to consistently use rst, so docs can My $0.02.
|
|
@nedbat regarding duplication between internal and external wiki; I agree we should eliminate all duplication there and remove the internal wiki page |
|
I'm not sure how this got to be about duplication between two wikis :-). The issue is simply does the "How To Contribute" doc just live in the GitHub wiki or does it also live as the CONTRIBUTING file in repos? I argued against having to copy the same text into 20 repos as keeping them all in sync would be a nightmare so I was in favour of (and started to implement in this PR) each repo having a CONTRIBUTING that simply links to one GitHub wiki page. @singingwolfboy was concerned this would mean too many clicks to get to the page, so I offered the compromise of only duplicating the wiki page in the edx-platform repo and not the other 19. I have a slight preference for no duplication and requiring an extra click (and am happy to revert to my original PR which did this) but I'm also happy to merge this PR as is (with the compromise of duplicating the file just once). |
|
@jrbl If we want to enable frictionless ad-hoc fixes of nits, then let's just agree that those kinds of changes don't need pull requests. Moving all of the docs to a wiki is overkill. The fact that the wiki can be used like a github repo is irrelevant because a) no one uses it that way; b) it's a separate repo from the code. As you say: the farther from the code, the less likely docs are to be updated. Surely a separate wiki (even with a repo) is farther from the code than doc files in the source repo. |
|
I concede the point, @nedbat. Either way, I'm not trying to hold things up. |
|
So where are we on this? Can we merge this pull request? It may not be everyone's preferred solution, but I think that having a CONTRIBUTING file is better than not having one. |
|
I'm just going to merge this as it's an improvement over the current state. If we want to further improve it, we can do so in other PRs. |
Include / Link to How To Contribute wiki page
Fix alex vsepr 2 mitx
MCKIN-6615: Bump xblock-scorm version to v2.0.8
…xblock Fix Done xblock update
5 participants
Created a CONTRIBUTING.md which GitHub will pick up and included the contents of the How To Contribute wiki page there. Also added a link to the wiki page in the README "How To Contribute" section.