Hacking session wiki structure

[gasche]

There was an ongoing discussion on the use of the ocamllabs compiler hacking sessions wiki in two related threads:

• https://discuss.ocaml.org/t/ocaml-hacking-session-at-mit-cambridge-us-on-june-6th/334/28
• https://discuss.ocaml.org/t/ocaml-hacking-session-in-belgium-1-2-july/374

Today I went ahead and reorganized the wiki, with the goals of:

1. improving the overall structure
2. making it not specific to events organized in Cambridge UK (the more consistent and well-established place for such events so far)
3. de-emphasizing contributions to the compiler codebase only (we want a list of tasks that scales to arbitrary OCaml projects that are useful to the community) -- also, de-emphasizing code patches as the only form of contribution (tests, documentation, communication are also important and valued).

New structure

Home page

The home page explains what OCaml hacking sessions¹ are, list future and past sessions, and points to a list of contribution ideas (on a separate page for readability). This page should remain short if possible.

¹: I'm not attached to the name, hackaton or "contribution parties" or whatever is fine

Contribution ideas

The things to work on page points to project ideas across the OCaml ecosystem; the previous content of the page (ambitious language changes or compiler hacking ideas) moved to Compiler or Language projects to work on.

This page should remain short if possible. In particular, we should push projects to move the content currently on this page into their space, in a CONTRIBUTING.md document or a wiki page of their own. Ideally, all OCaml projects interesting in participating to these events would tag/label issues on their issue tracker, and we would just point to that (and their landing page for contributors). Currently this is not the case (Lwt and mSat have one single issue that is being pointed out, ocaml.org does this weird thing of having a meta-issue about contributions), but I think we should pressure projects into adopting this more standardized structure (I'll start complaining very soon), and push back against attempts to add more project-specific cruft to this page. Otherwise it will be an unmaintainable mess soon.

The rest

The rest is still in flux.

Stuff we could remove

These are pages that I believe could be removed, because they don't provide much non-redundant information and/or would be best moved to project-specific locations.

• https://github.com/ocamllabs/compiler-hacking/wiki/OPAM-bulk-logs
• https://github.com/ocamllabs/compiler-hacking/wiki/Compiler-documentation
• https://github.com/ocamllabs/compiler-hacking/wiki/Contribute-to-ocaml.org

Stuff that actually makes sense on a "compiler-hacking" wiki, but not so much on a "contribution/hackaton organization" wiki

It's not clear to me what is best. In fact I would be tempted to say that a "compiler-hacking" repo should remain with the content below, and that the stuff above (contribution/hackaton organization) should maybe move to a different wiki. Opinions welcome.

• https://github.com/ocamllabs/compiler-hacking/wiki/Multicore-OCaml
• https://github.com/ocamllabs/compiler-hacking/wiki/OCaml-Multicore-Runtime
• some compiler/language projects have their own pages:
  • https://github.com/ocamllabs/compiler-hacking/wiki/Add-a-%22with%22-syntax-for-patterns
  • https://github.com/ocamllabs/compiler-hacking/wiki/Value-specifications-in-structures

Log pages

For the recent hackaton at MIT I created one log page, and I did the same for an old 2014 event that I transferred from its own page. There is also a Summaries page that contains the logs of two separate events, and a series of blog post that are essentially (restructured) logs.

I'm not sure what to do with log pages. I think that preserving them is valuable (important), and that making a distinction between "raw log of activity for each person" and "restructured/rewritten communication in a blog post" makes sense. Having a separate page for each log is natural, but Github wikis have a single panel on the right with all pages that is important for navigation (I've seen at MIT that people rely on it a lot), so not cluttering it is good.

I would be tempted to propose that ongoing events have their own log pages, but that after they are finished the logs are moved to a single "Summaries" page and the event-specific log page be deleted. What do people think?

[gasche]

(cc @avsm @GemmaG @yallop )

[yallop]

Thank you for your work on structuring/organising the wiki, @gasche.

I've no objection to the wiki being repurposed. Circumstances have changed, and the original Cambridge compiler hacking wiki is no longer useful in its current form. It was initially created with the goal of supporting the events we held in Cambridge, and served its purpose well. However, the list of projects is no longer maintained because the original organisers of those events are no longer actively involved with them. Retiring the wiki, and moving anything that's still useful on it elsewhere, seems like a good plan. (And reorganising and renaming the wiki in place is a reasonable enough way of doing that.)

[dannywillems]

Hi @gasche. Thanks for your very useful work.

About the event name, I think OCaml hacking session is a very good name. Compiler-hacking seems wrong as it's not only about the compiler.

I think it could also be interesting to have a list of useful projects which the community needs or projects that can be useful for other developers and companies (not related to the compiler or the documentation). I have an OCaml projects list on my todo list. I will share it very soon, just need to gather all things in one place.

[avsm]

Likewise with @yallop, many thanks for taking the initiative to reorder and begin the broadening of the event, @gasche!

[GemmaG]

@gasche @yallop @dannywillems @avsm Thanks for all of the suggestions and edits!

Perhaps we should create a new repository within the OCaml organisation on GH specifically for these hack events, and take advantage of a fresh new wiki that we can organise in a concise way? I think it should be separate to the ocaml.org repo. We can then use the Discuss forum to promote/mention upcoming events, and to communicate with those that sign up. If needed, we could set up a specific mailing list, although I think the email options on the Discuss forum mostly cover that - we would just need to ensure that all of those who want to attend the events also sign up to the forum :)

I would also agree that moving older logs to a single "Summaries" page makes sense - once the logs of a specific event have been summarised into a post/review they no longer need to be individually accessible from the menu.

[avsm]

@GemmaG: A fresh wiki makes sense to me -- let me know if I can help create one on the ocaml/ organisation.

@gasche: I agree that some topics like the OPAM bulk logs are deprecated. Perhaps we should put out a call on opam-devel for opam/opam-repository-related junior jobs (especially around areas like packaging on OS distros that would benefit from wider help).

It would also be good to ensure that ocaml.org links to the new page when it is created...

[gasche]

Yes, what about a ocaml/contribution-events wiki? It could also serve as support for GSoC or other such longer-term contribution events if we organize some again in the future. (I'd like to kick the can for an OCaml GSoc organization next year, but I won't have any time for that before September.)