Can we stop using git(hub) for RFCs?


#1
  1. I have to deal with a repository, which means dealing with github, forks, git commands, etc. This is something I dread having to deal with just so I can write some text. Some people will probably be too lazy to actually do this to write an RFC. Especially people who don’t have a github account already.

  2. I had to actually create a new RFC because I tried to update an old RFC, but then I’d need huonw to pull my changes. This means I have to split up the discussion between https://github.com/rust-lang/rfcs/pull/886 and https://github.com/rust-lang/rfcs/pull/1940

Can’t we just use a wiki? Then anyone can change parts of the RFC without having to submit PRs to the original author. Furthermore, you don’t have to clone the repo, manage several branches, etc. Since wiki software is already made to keep revisions of formatted text. You can see how your changes look instead of having to write in Markdown and hoping it renders okay.

##Downsides

I don’t know which wiki software does a good job with making line notes on each “article”. That’s probably the best feature of github PRs in regard to RFCs.

##Discussion

People yelled at me in IRC because I didn’t know git well, that I’m supposed to keep the git history clean without merges, it’s very frustrating.


#2

I think GitHub’s new “Squash and Merge” button can help with this: https://github.com/blog/2141-squash-your-commits

I use it on my repositories and then you don’t have to ask contributors to rebase and squash themselves (something that is tricky to do right manually as you’ve noted).

I don’t know if the Rust GitHub projects are using this feature or not.


#3

If people are yelling at you on IRC, that’s unacceptable. Please let the moderators know about that.


#4

I am also not a fan of discussion on GitHub. I’ve toyed around with many ideas for how to setup RFCs and so forth, but I’ve not found something I like better all around. For larger RFCs that will take some time to develop – or a group of related RFCs – I think creating a separate repo can be a good approach. Wikis might be suitable, but in general they don’t support discussion very well. A separate repo allows you to open issues, take pull requests, etc.

I’m also a fan of the idea of having GH basically consist of links to discuss threads, with people writing summaries of the key outcomes of each discussion. But that requires a lot of manual effort and doesn’t often happen.

Tricky problem!


#5

Yes, I’m not a fan of my exact solution either. But I feel like the person who puts in a pull request has too much responsibility since they have the final say on how the RFC looks like. So they have to update it when issues come up in discussion. I don’t see much of multiple people fixing the same RFC until it’s accepted because it’s more of a bother to do a pull request of a pull request.


#6

I think the design of the RFC process is such that a single person or a small group of people propose an rfc and decide what goes in it, so a wiki would not work great. When you do want to collaborate, you can always hand out push access to your fork.

The rfc process is centered around review and discussion, neither of which work well on a wiki.

Really, it’s totally fine to work on an RFC via the github UI, in which case it’s almost no different from a wiki in the first place; with the caveat that you have to make the initial fork and make it into a pull request, neither of which are too complicated. We could add better documentation for this workflow, perhaps.

It’s unacceptable that you got yelled at in IRC for this. You don’t even need to keep the history clean here, the rfcs get squashed and moved by the team before being merged.


#7

I think I got yelled for more like saying it’s awkward to use Git, rather than the particulars of my pull request. Still, Git shouldn’t be a requirement to use Rust or contribute to RFCs. Some people prefer using other version control systems.


#8

Not sure if it shouldn’t, but it is. Everyone working on a single project necessarily needs to use the same VCS (or one compatible with the main one). Which VCS is used is determined collectively by the project, not by the preference of individual users. If you want Rust to switch to a different VCS, you can propose an RFC for that, but I sincerely doubt it will get any traction.


#9

Again, you don’t need to know much about Git to use the online editing interface; you’d need to learn that amount of tooling to work with wikicode anyway.

Yes, this will lead to a messy git history in the rfc, but like I said, this doesn’t actually matter much.


#10

it’s a little bit more complicated when you’re trying to edit someone ELSE’S RFC since it’s not merged yet

Edit: I messed it up and accidentally committed to my master branch, damn it


#11

Write, ilke I mentioned the process as designed isn’t supposed to be one where that’s too common (and if you are collaborating on an rfc, grant access to the repo)


#12

You’re right, I’ll go track down huonw and get right on it. My point is you never know if your RFC later needs to be updated or handed off to another person.

Maybe my ideal system is closer to StackOverflow where anyone can suggest edits, but moderators can approve/disapprove them.


#13

Google Docs allows commenting and proposing changes. It’s not so good with markdown and archiving though.


#14

Whether or not git is required to contribute to Rust (which it inevitably will be, whether directly or through an extension to another VCS that talks git like Kiln Harmony or something), GitHub should not be. GitHub is proprietary software and the company behind it is pretty shady.


#15

I’m following the issues with RFC/discussion tooling since some time now.

With the goal to solve many of the problems that arise in a large group of collaborators, a friend and I started to work on a new kind of collaboration project.

The core idea can be imagined as a mix of the expressiveness of mind-mapping, Wiki and realtime collaborative editing.

I mentioned the first prototype (https://github.com/woost/wust) earlier. With all the things we’ve learned from the first prototype, we started a second one from scratch: https://github.com/woost/wust2. It is in an early stage of development, but you can already play with the online demo and try basic collaboration features: https://wust.space

The large Rust community seems like a very good use-case for our system, so we are very open to implement improvements to support the Rust development process.

Please ask me any questions.


#16

If we forget the “need” to use markdown for a minute, wouldn’t Google Docs have all the features the RFC process needs?


#17

I believe you could achieve a lot with Google Docs. Realtime collaborative editing is great for working on content together. And the fact that everybody can edit everybody else’s contributions is good for having discussions inside the document and continuously refactor and clean up. But conceptually you only have the realtime-advantage over a wiki.

It’s a bit inflexible if you want to share the same content between different documents. At the same time, it is tedious to keep links, backlinks to other documents and overview documents up to date.

And of course it’s not open source, but there are alternatives.

Edit: I forgot to mention that the commenting feature would work like the line-based notes on github.


#18

Also, there’s no way to link to a specific revision of a Google Doc. I’m not even sure if people other than the owner can see the revision history at all.


#19

My impression is that RFCs are not meant to be collaboratively edited in real time in a single session, but rather collaboratively discussed/reviewed over a long period of time and typically only updated by the original author. In particular, I think any credible replacement for github for RFC purposes would need to provide the ability to

  • comment on specific parts of the RFC
  • reply to any comment
  • link to any past comment
  • have a complete public edit history
  • link to any past edit or part of a past edit
  • subscribe to/unsubscribe from all updates/comments on a particular RFC
  • somehow support an equivalent of fcpbot

As far as I know, google docs doesn’t offer those features, since realtime collaborative editing precludes a lot of them. I can’t seem to find any of them in wust either, though that may only be because I can’t figure out what on earth is going on in that demo.


#20

Sounds like Google Wave, if only that were still usable :sob: