New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: Stencila Collaboration via Git #556

Open
michael opened this Issue Feb 12, 2018 · 5 comments

Comments

Projects
None yet
3 participants
@michael
Copy link
Member

michael commented Feb 12, 2018

Just had an idea of a collaboration flow we could implement with a minimum of infrastructure to be provided by Stencila.

Open Collaboration Workflow

Me:

  1. Open Stencila Desktop and create a new project

  2. File -> Save project on disk (e.g. ~/my-dars/our-paper)

  3. Share project via Github

    $ cd ~/my-dars/our-paper
    $ git init
    $ git remote add origin https://github.com/michael/our-paper.git
    $ git push origin master
    
  4. Share Github Repo

Them:

  1. Clone the Repo, make changes in the editor and push them

    $ git clone https://github.com/michael/our-paper.git && cd our-paper
    $ stencila . # brings up Stencila Desktop for editing
    $ git add *
    $ git commit -m "reworked introduction chapter"
    $ git push origin master
    

Me:

  1. Accepting the fixes

    $ git pull
    $ stencila open .
    
  2. Publish on Stencila Hub or a Publisher

  3. Paper is now available in a reproducible version at: https://stenci.la/michael/our-paper and after peer review at https://elifesciences.org/articles/article-id

Considerations

  • Stencila works with bare-metal tool (no platform lock in)
  • Use the workflows and tools you prefer (Gitlab, Github)
  • Use existing reliable infrastructure
  • Keep Stencila Hub slim and maintainable (we use it as a public repository for hosting publications, so people can run them, play with them in the browser and download or clone them to run and edit them locally)
@apawlik

This comment has been minimized.

Copy link
Member

apawlik commented Feb 13, 2018

Looks like a very good workflow. If possible, it would be great to have GUI for doing the commits in Stencila (like it is now available in RStudio). This makes it easier for people who don't use Git - though it is still worth it to, at a later date, to look for solutions for people who do not use version control.

@michael

This comment has been minimized.

Copy link
Member

michael commented Feb 13, 2018

Yeah we can definitely consider tightly integrating with Git. We just need to have a sound plan of the complete workflow before we do so.

One way to approach it could be that we let the user do a git init in the folder, and once that is done the Desktop app could recognise that and show a prompt for a commit message when you hit save.

Btw you can try out this workflow by following the steps here: https://github.com/michael/documents

@apawlik

This comment has been minimized.

Copy link
Member

apawlik commented Feb 14, 2018

Thanks @michael
I wonder if it would be possible to allow for git init from the Desktop app too? It would be available only in a project would be open (i.e not a single file). I think this is how it can be done from RStudio GUI - you can do quite a few things via the menu, without having to use command line or a separate Git GUI. That would be a lower barrier for many users,

One more thing (which is something I haven't yet thought :) ) is conflict resolution. But maybe the workflow first.

@oliver----

This comment has been minimized.

Copy link
Member

oliver---- commented Feb 14, 2018

@michael be careful with your proposal and the assumption that git is the solution for collaboration in our case. If it was we would not need the whole OT stuff at all.
Git works pretty well for unstructured text files (such as source code, or markdown files). It does not work for XML files, at least not without an XML aware diff/merge tool.

It will not be very likely that we will provide a conflict resolution UI, because this exposes the complexity of git conflicts to users which I don't think is easy to grasp. Also it requires an XML aware diff/merge tool, which does not exist, at least not free or open-source.
The idea with combining git and OT was primarily, to have an easy file-system based implementation, that can deal with binaries and allows rolling back etc.

If we used unstructured text files as serialization format, we could allow for a collaboration between coders and clickers, where clickers contribute PRs (using WYSIWYG editor with OT based group authoring) and coders work with git directly, doing merges and resolving conflicts.

@michael

This comment has been minimized.

Copy link
Member

michael commented Feb 14, 2018

As @oliver---- mentioned with this workflow you are likely to experience merge issues, as Git does not work well with XML content. There are tools to help with merging XML. In the long run we will additionally provide realtime collaboration, and automated merging of XML diffs (the editor will do the XML merge for you, and just highlight places you should review after the merge)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment