-
Notifications
You must be signed in to change notification settings - Fork 99
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
Online editing #23
Comments
So on July 28 I contacted Informatics Computing Services about getting authentication behind Informatics' Cosign service. Today we've gotten the OK at first sight, and they are going to discuss this next week (person managing the Cosign service is off work this week). This is looking positive! |
We have the Cosign service working in a quick telnet-esque test. Here's the game plan:
then, one of the following: A) write a new website in Ruby (with the use of gollum) to edit the content repo |
This is going pretty well! I've written a library to interact with the CoSign daemon. Anything living on Tardis can interact with cosign-webapi instead. Proof of concept of CoSign working can be found here, on the map! (Log in on the map before visiting the next link..) A Better Informatics "API", of sorts, can be found at provider.betterinformatics.com (https only). The code for bi-provider is open-source, of course! |
That Cosign thing is very neat indeed.... I started typing things and realised I have no idea what I'm talking about RE editing, but I'd probably vote for having the site remain on Jekyll. Alternatively and an idea that you haven't already mentioned, is maybe even serve the site content as Markdown files direct from the repository and then use a client side library to parse the MD on the fly. Then for editing, just click to swap to the raw MD. How you'd get the changes back to Github is another question entirely and would probably need something awful. |
I think the way to go here is simply use commits signed by the cosign user. |
Oh of course, because in Git there is no authentication on who you say you are in the commits is there? So we could give the back-end an API key which it could use for all users' edits? Also just come across this that might come in handy: Github Contents API |
You dont need that, you can simply commit the changes and sign it with the
cosign email.
…On Tue, 7 Nov 2017, 20:30 Robert Phipps, ***@***.***> wrote:
Oh of course, because in Git there is no authentication on who you say you
are in the commits is there? So we could give the back-end an API key which
it could use for all users' edits?
Also just come across this that might come in handy: Github Contents API
<https://developer.github.com/v3/repos/contents/>
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#23 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAL1KIwQv9XA2XYu10X0LFXMmPJJFI09ks5s0L31gaJpZM4OSMTx>
.
|
But to push to the repository you need to authenticate? |
(assuming this still needs you to be on the CompSoc Github team to push) |
I'm hoping for us to integrate editing within the Better Informatics website. It shouldn't be just 3-5 people contributing content, and people are much more likely to contribute if they can click a big edit button and make a change immediately, rather than having to create a GitHub accounts. Unfortunately a lot of students don't know how to use Git. Right now my plan is:
Moving away from Jekyll would be ideal as we don't have that many pages, and we have a lot of metadata (about courses) that could be pulled externally (such as what semester courses are in, what courses are available, course names, etc). But even when moving away from Jekyll, all the real content would still be stored in markdown files, visible on GitHub. |
We can use GitHub Apps.
This makes this feature a whole lot more possible! It means we don't have to deal with races between the bi.tardis.ed.ac.uk and the GitHub copy of our repository. The cool thing here is that we can create commits as users themselves (potentially from the client). Because trees must be created before creating commits we could actually support editing multiple files in one go (although we probably technically don't want this as this would result in non-gitty commits, but that ship has probably sailed). The interface could look like this (just a quick idea and a quick drawing): After clicking "save" we can show them a diff and ask them to write a commit title/message. We can ask them if they have a GitHub account or not and either:
The advantages of user-to-server requests here aren't clear, as we can create a commit as them whether or not they like it. Adding them to the organisation would be nice, though. |
So a possible future direction for this is Netlify's NetlifyCMS. Their CMS itself is a fairly opinionated React app, but as part of that they've open sourced a proxy to the GitHub API that allows for client side commits to be made, which we could integrate into an editing thing inline on BI. I'll have a play around and see what the feasibility of this might be, but it could be a good way forward fo getting more people contributing. |
TLDRProof of concept is now up at bi.comp-soc.com In more wordsThis has been a bit of a saga, and has entailed some fairly fundamental changes to a lot of In essence, what I've done is split out the engine of BI from the content. The content still lives in the On to the exciting stuff — online editing! The general flow is:
Any thoughts? This is a fairly bare description, but I can expand on any bits of it that are unclear. I'm of the mind that this direction would get more contributions, because it would be drastically easier to contribute, but I'm aware that it does entail a fairly sweeping change. (CC @compsoc-edinburgh/sigweb) |
👍 👍 👍 💯 💯 Love it.
cool! How does that work? Just it just serve from the gh-pages branch (from which repo?) or does it do away with gh-pages altogether (i guess netlify handles the building too)?
BI has an open source license for https://ckeditor.com/ laying around if we want to add WYSIWYG support later. WYSIWYG can be quite complicated to do nicely though (especially rendering TO markdown) so perhaps we should not look into this right now and exclude it from the 'minimum viable product'. (i hate the MVP acronym.) Just putting this out there for documentation sake!
Yeah. Most things, Shouldn't be too hard to read the front matter (it's just yaml after all), merge in the user-provided 'quick links data', and write it back out to the front matter? Though, as above, front matter editing does not seem necessary for the first iteration.
Cool! Is this the frontend connecting to the backend here? https://github.com/compsoc-edinburgh/bi-engine/blob/master/save-section/index.js Where's the sauce for this? (Or is this what you're planning to commit when you're free? no pressure)
(I'm assuming source for the git-gateway thing is not available/implemented yet, so maybe some of these questions can be answered by reading the code) What's attribution like? I'd like to see commits of this form:
Where the real name and email address is derived from their GitHub account (it would show the same details as if they did it in the github web interface). There's some obvious complexity and barrier issues here (requiring the user to log in, but not requiring them to understand the rest of the GitHub interface). We can chat about that. In general what I'd like to (/ would not like to) see are:
[2*] For people to get commit credits, they'd have to be added to the org and team: https://github.com/orgs/compsoc-edinburgh/teams/better-informatics/members. That process is manual at the moment. WHenever I see someone make a PR I just invite them.
maintainer: are you thinking of limiting the ability to edit metadata / edit the repo directly? Or reduce the chance of a fuckup by not adding that ability to the web interface? (Just want to understand your thoughts here)
(I have to ask) is the URL just for the proof of concept? 🙂 All in all! Well done. Looks great so far :) Some edge cases to not forget about, in case it might be affected by online editing:
I'm really excited to see what's next and, if you decide to go ahead with this iteration, see this get deployed. Once we have online editing / this new framework down, we're no longer restricted to a static website, and actually have a base to work off. There's tons of possibilities (... such as tighter drive integration for past papers etc.) I'm hyped! 👌 |
P.S. in case you didn't know, we have this app set up here for API operations: https://github.com/organizations/compsoc-edinburgh/settings/apps/better-informatics |
Heya! Somehow i completely missed this in my GH notifications. Lemme start off by saying I really, really like this. Editing seems super smooth, and I dig how you can immediately get a WYSIWYG preview of your edits. I think that in-place editing of BI would lower the barrier for entry for maintaining BI—a lot of people aren't comfortable with Git or web dev (or both). With that said, I have some concerns about maintainability. This change adds a heck of a lot of dependencies onto the project, namely a rewritten templater (Svelte), a cloudflare worker/GH app to build the page bundle, and netlify for serving that static bundle. While these are all super cool, I think that this is fairly fragile. What happens if Cloudflare changes their pricing? Or if GH apps disappears altogether? Or netlify starts charging? Plus, with all these cloud services backing up the service local development is difficult to do. Ultimately, BI isn't really in a position to take on new technical debt. Our goal should be to ensure that BI is available as a resource to future generations of students, and to that end the website should have the minimum of moving parts possible—and those moving parts should be as boring as possible. With that in mind, I think the edit-on-Github flow works pretty well. Most students have a github account, each section is individually editable, and merge conflicts (should they happen) are very clearly marked. GH pages for hosting—while it is aggressively cached—still updates within 5-10 minutes of the underlying material changing. This is plenty fast enough for what is ultimately a read-heavy workflow. GH pages isn't going anywhere, Jekyll isn't going anywhere, why not build off those? Alternatively, if we do need a BI interface with attribution+proper merging+good history support+WYSIWYG editor, should we think about using an off-the-shelf wiki solution? Something like Gollum seems like it would fit our needs without fully re-inventing the wheel. I really really don't want this to sound like an attack—I absolutely love bi.comp-soc.com. It's a really cool project with some very clever code behind it. I'm just concerned about the maintainability going forward. If there's a way to do in-place editing while also limiting the complexity, I'm all for it. |
So I also really like this, but at the same time I agree with kage's concerns to an extent. I think this is a good proof of concept but it could definitely do with being streamlined. One more thing which I would be concerned about is vandalism, unless I'm missing something there's no login or way of tracking who has done what in this implementation - and I think we would need some sort of login (probably with cosign?) and way of blacklisting people to ensure we don't end up with vandalism taking place. I know this is a quick PoC though, so I'm not saying this as a criticism - more something we should heavily consider if we do go ahead with this idea. One other thing is that I like how bespoke BI is and wouldn't want to move to a completely out the box wiki service because I feel we would lose some of the "homeliness" for want of a better word, on the frontend at least. |
Thank you all for the feedback, I very much take it in the spirit it was intended and not as an attack. To go through things one by one:
There's a GitHub Action which compiles the site into the
This would be a bit of a tricky one, especially in terms of preserving markdown compatibility. I haven't specifically looked into
It is indeed. It connects through a Git Gateway instance setup with the correct repo and my GitHub account, but that's just for right now—it could absolutely use a GitHub app in future. All it does is call the needed GitHub API endpoints to make a commit with a file modification.
This was a quick POC and so the commit messages are admittedly terrible 😂. That's definitely something to fix. Requiring a commit message before saving is a good thought, it should help with keeping track of history. The bigger auth question though is definitely something to be discussed. Right now (as you mentioned @findoslice) there's no authentication or identity checking, and I agree that could lead to vandalism. I have a hope that it wouldn't, and that our fellow students are better than that, but realism must prevail. I think in general I'm opposed to requiring GitHub accounts, because although a lot of students do have accounts not all of them do, and they probably wouldn't create one just to add some notes. I'd agree with having an option between GitHub and CoSign though—seems like the best of both worlds, with students either able to get commit credits on GitHub or have a really low barrier to entry.
Not necessarily thinking of limiting it, but in general I don't think being able to edit the metadata for a section should have a lowered barrier to entry, as it shouldn't happen very often, and could have unintended side effects.
You're not wrong. This adds a ton of complexity, and it may ultimately not be worth it. I do think though that improving the editing experience is worth a bit of extra complexity, although admittedly not necessarily as much as added here. Some suggestions to help with that:
There's a lot here, so I've probably missed a point or two (if so, do bring them up again) |
|
A long term plan is to get editing right within the website, rather than just on GitHub.
gollum / gollum-lib seems like a really good base, but this will not be an easy feat.
The text was updated successfully, but these errors were encountered: