How to contribute to wiki pages

[tjfulle]

@bartlettroscoe, how does one contribute to the wiki pages? It don't see a way to fork the wiki so that I can submit a PR. Nor do I see any create new page/edit page buttons. Should I just clone and send a diff to someone?

It seems valuable for new developer, such as myself, to give input to the wiki (at least to the new developer/building Trilinos pages) while the pain of ramping up is fresh on their mind...

[bartlettroscoe]

@tjfulle,

GitHub really does not directly support a PR model for updating the wiki. But I prototyped how to do it with:

• https://github.com/bartlettroscoe/TrilinosWiki

My recommendation was to create:

• https://github.com/trilinos/TrilinosWiki

which is a clone of:

• https://github.com/trilinos/Trilinos.wiki.git

and then you can do a PR against the 'master' branch of the https://github.com/trilinos/TrilinosWiki.

If you want, I can do a review for you using my https://github.com/bartlettroscoe/TrilinosWiki repo. I can provide the exact git commands you need to run in order to do this if you are interested. Let me know.

CC: @trilinos/framework

[tjfulle]

Thanks @bartlettroscoe! I'll cloned https://github.com/trilinos/TrilinosWiki and I'll go from there.

I was going to add some information about building Trilinos with Mac OS X, but the wiki doesn't have a building page/tab to link from. Do you want to add a place-holder page for general build instructions that I can link off of?

[tjfulle]

Looks like https://github.com/trilinos/TrilinosWiki has a 404 error.

[jhux2]

@tjfulle I suspect @bmpersc or @jwillenbring needs to add you to the right permissions group.

[tjfulle]

@jhux2, ya, probably. When the switch is made to a PR model in #1155, contributing to the wiki might be something to think about?

[bmpersc]

I don’t think permissions are the problem. I get a 404 at that link too and I should have all the permissions. Is https://github.com/trilinos/Trilinos/Wiki the right url instead(Note the “/“ between trilinos and wiki.)? That one works for me, but I'm not sure that is the wiki you are talking about.

[bartlettroscoe]

Sorry, for the confusion. I had proposed some time ago to create the GitHub repo:

• https://github.com/trilinos/TrilinosWiki

and I prototyped this with a repo in my account:

• https://github.com/bartlettroscoe/TrilinosWiki

The repository https://github.com/trilinos/TrilinosWiki does NOT yet exit. But I will go ahead and create it since I think that is the best workflow for proposing changes to the wiki.

[jhux2]

I don’t think permissions are the problem. I get a 404 at that link too and I should have all the permissions. Is https://github.com/trilinos/Trilinos/Wiki the right url instead(Note the “/“ between trilinos and wiki.)? That one works for me, but I'm not sure that is the wiki you are talking about.

@bmpersc, Tim doesn't see the edit button on the wiki. I have some vague memory that there's contributor write permissions ... but maybe I'm misremembering.

[tjfulle]

@jhux2 , I think you're right. I thought there was a wiki setting to allow more permissive editing, but I haven't been able to figure it out on my own repos. It would be a real hassle if the only way to contribute to the wiki is by PR, particularly if Trilinos adopts a restrictive PR model where relatively few developers have write permissions.

[bartlettroscoe]

@tjfulle, I set up the GitHub repo https://github.com/bartlettroscoe/TrilinosWiki. Look at the README.md file that I created to explain how to use this to suggest changes to the wiki using PRs:

• https://github.com/bartlettroscoe/TrilinosWiki/blob/master/README.md

As an example, see my PR:

• Add link to TriBITS Lifecycle Model Overview TrilinosWiki#1

If you have any questions about that process let me know. I will add a section on how a @trilinos/framework team member can actually merge this back to the target Trilinos wiki repo:

• https://github.com/trilinos/Trilinos.wiki.git

It is pretty simple if you are comfortable with branches and multiple git repos.

Let me know how it goes.

[bartlettroscoe]

@trilinos/framework,

Any desire to comment on:

• Building on osx TrilinosWiki#2

?

Otherwise, I will merge and add to the wiki.

[bartlettroscoe]

I added the section:

• https://github.com/trilinos/TrilinosWiki/blob/master/README.md#reviewing-and-merging-pr-branch-to-trilinos-wiki

to the instructions and followed it to merge the branch in trilinos/TrilinosWiki#2 and close the PR.

I am now moving this into to review.

[jhux2]

I added the section:

https://github.com/trilinos/TrilinosWiki/blob/master/README.md#reviewing-and-merging-pr-branch-to-trilinos-wiki

to the instructions and followed it to merge the branch in trilinos/TrilinosWiki#2 and close the PR.

I am now moving this into to review.

Boy, this sure seems like a lot of work, when it seems like there's something wrong with permissions on @tjfulle's account. Here's what I see when I try to edit the wiki:

[tjfulle]

@jhux2 , there is nothing technically wrong with permissions, I am listed as a member of trilinos/Trilinos, but not a "contributor". But, it sure is a pain to contribute to a wiki, if non-contributors have to clone a different repository, create the markdown page, open a pull request, then a Trilinos contributor has to edit the new page to link it to the existing wiki site, ... It seems to defeat the purpose of a wiki. Unless there is a real danger of people maliciously sabotaging the wiki by posting bad information, I believe the wiki should be opened to allow contributions from any GitHub member.

[tjfulle]

@tjfulle said:

I believe the wiki should be opened to allow contributions from any GitHub member.

Just uncheck trilinos/Trilinos Settings > Restrict editing to collaborators only

[bmpersc]

@jhux2 @tjfulle I don't believe not being a collaborator is the issue. We don't have any setup right now. I did go poking around the membership lists and the best guess on why you don't have the edit button is that you are not in the "developers" team which is required to have write access to the Trilinos repos and I'm guessing the wiki. Let me look into if it is appropriate to add you to that team.

[bartlettroscoe]

Unless there is a real danger of people maliciously sabotaging the wiki by posting bad information, I believe the wiki should be opened to allow contributions from any GitHub member.

I am not sure that is the best idea unless we can find a way for GitHub to send out email notifications when a wiki page is edited. (That is how Wikipedia is kept correct even if everyone is allowed to edit it. Without email edit notifications, I suspect that Wikipedia would be a complete mess.) But GitHub does not seem to directly support for email notifications when the wiki gets updated, as mentioned at:

• https://webapps.stackexchange.com/questions/78567/how-to-receive-a-notification-when-someone-edits-my-projects-github-wiki

But any Trilinos developer should obviously be able to edit the wiki without having to go through a PR.

But for larger suggested changes or additions from outside contirbutors, I think going through a PR model seems like it would be a reasonable thing to do.

[jhux2]

GitHub does not seem to directly support for email notifications when the wiki gets updated, as mentioned at:
https://webapps.stackexchange.com/questions/78567/how-to-receive-a-notification-when-someone-edits-my-projects-github-wiki

@bartlettroscoe That's too bad. But in that same link, using an RSS feed is mentioned. To see changes to the Trilinos wiki, here's the feed to subscribe to: https://github.com/trilinos/Trilinos/wiki.atom.

[tjfulle]

Thanks everyone for the help. I now have permissions to write to the Trilinos repo and, thus, the wiki. I think @bartlettroscoe has sufficiently documented what users would need to do to contribute to the wiki, so this issue could probably be closed.

FWIW, my opinion is that the wiki should be more open. I understand the points brought up as to why it is not (more open), but I believe the benefits outweigh the risks :)

[tjfulle]

@bartlettroscoe, feel free to close this issue, unless you think it warrants more action.

[bartlettroscoe]

feel free to close this issue, unless you think it warrants more action.

Thanks. Closing as complete.