Organize GitHub Wiki

[DragonmasterJ]

Need to figure out how to use the GitHub wiki – can we organize our wiki pages into folders in the repository so our generated files stay separate from hand-written static files?

[jawaad-ahmad]

Summary

For now, we can keep our ICD as a Markdown file as-is on the wiki with the following exception: We can remove arguments, return types, and the method description from the Markdown file. In its place for each method, we put a TODO or something for now pointing to the docstring in the .py file for reference.

This will keep both pieces of the document in their respective places with no duplication. Down the road, we can investigate a tool or set of tools to merge into a pretty generated wiki page, or a pretty generated HTML page to put on the GitHub Page for this repo.

tl;dr

I played with the wiki a bit. If we work from the repository directly, we can organize pages into subfolders as needed. This means we could have something like a src folder for source documents that we hand-edit, a generated folder for files generated by running some tool, and any other folder structure that we want.

All of it shows up flat on the wiki when going through the web interface, so if we have a src/One.md and generated/Two.md, then on the wiki we still browse to http://.../wiki/One and http://.../wiki/Two as if the folders weren't there.

This makes it interesting if two folders have the same-named file. I don't know which gets picked, but only one is accessible and the other isn't, so best practice is not to have multiple files with the same names.

As stated before, I believe the wiki supports rendering Markdown and Textile depending on the file extension. It seems we've settled on Markdown for all our files, so we'll proceed with .md files only.

When working via the repository, we can branch to our heart's content. This makes it very easy to support any parallel developments because the docs can stay in-sync with exactly the code they reference, so if we're working on the hsdc2016 branch, we could work on our documents on an hsdc2016 branch in the wiki repo as well.

The limitation is that documents worked on any branch other than the master are not visible on via the wiki web interface, meaning the hsdc2016 branch needs to be released and merged to main for us to publish our documents to the wiki.

I recommend we leave this alone and continue working on master for the time being until we have a need to do otherwise.

I also recommend against using folder until we have a need to do so.

[ellerychan]

Your tl;dr is longer than the first bit. :-)

It sounds pretty good, but my foundational mental model of the wiki is still unclear. It looks like the wiki is an independent repository. If so, we can clone it, edit locally, and push to it. But we can also edit pages directly on GitHub. Is each edit a new commit that happens behind the scenes?

The wiki does not have the normal repository view where you can see the commits and switch branches. You say it always just displays the master branch, so it doesn't play well with our proposed branching scheme for hsdc2015, hsdc2016, etc.

I think the wiki is useful as a set of working documents, so I think we should just work in master, or work in a branch parallel to our code repo branch, then merge in to master.

We can put off the figuring out how to snapshot it to go with our final code until after Feb.

[DragonmasterJ]

If it works like Google Code's wiki, it would be the case that every time it's edited on the web it's a commit under the hood.

[jawaad-ahmad]

It sounds pretty good, but my foundational mental model of the wiki is still unclear. It looks like the wiki is an independent repository. If so, we can clone it, edit locally, and push to it. But we can also edit pages directly on GitHub. Is each edit a new commit that happens behind the scenes?

Yes, we can clone the wiki repository very easily. That's how I played around with it. When you browse the repository via the web interface, you'll notice a clone URL on the right-hand side with the message, "You can clone with HTTPS, ...."

When you're browsing the wiki, you'll see a similar message on the right-hand side, but if you look carefully, you'll notice the URL is now for the wiki and not the repository. One interesting note is the wiki URL given is only an HTTPS URL, but I've been cloning via SSH without any problem.

If I have a code repository xyz, then its wiki repository is xyz.wiki.

The wiki does not have the normal repository view where you can see the commits and switch branches. You say it always just displays the master branch, so it doesn't play well with our proposed branching scheme for hsdc2015, hsdc2016, etc.

Yes, we can edit pages directly on GitHub. Behind the scenes, yes, each edit is a new commit. I presume the edit message we supply is the commit comment.

I think I've gotten bit by making changes in both places simultaneously at times--not just here, but back on Google Code as well. It resolves itself the same way as any other push/pull in Git.

You're right. Although it's a full-fledged Git repository, the wiki does not appear to give us the CM experience via the web interface as the code repository does.

If we were doing something more advanced such as parallel development, we might want to take advantage of branches in the wiki repository at that time; for now, I see no reason not to stay on the master and work in the main folder.

I think the wiki is useful as a set of working documents, so I think we should just work in master, or work in a branch parallel to our code repo branch, then merge in to master.

Agreed.

[jawaad-ahmad]

Also this idea originated during the discussion of #96.

Regardless of where the various design documents are, I think it would be valuable to have a central index that links to them all. I don't know of an automated way to make sure that index stays up-to-date, so it will probably take a little effort on someone's part to provide that oversight.

It shouldn't take much time to set up and then maintain. It's just that someone or everyone would have to stay on top of it. It can be understood that each person that starts a new diagram is responsible for going to a Design Document Index page on the wiki and add a link to it.

Each time someone states, "I'm starting a..." or "I'm going to start a...", someone else can provide a gentle reminder:

Please remember to update the [Design Document Index](../wiki/Design-Document-Index).