How would you improve GitHub?

[FinnWoelm]

Hi OSM,

I've been having conversations with @mattodd about alternatives to Github for collaboration and communication. He asked me to expand the conversation to everyone, hence this issue.

My colleague and I spent the past 18 months building a web platform with GitHub's functionality but made for documents (in Drive/Dropbox or on your pc) and focused on simple UI/UX.

Unfortunately, we were blinded by enthusiasm when we started developing our platform and so we never asked the community whether what we are doing is actually helpful and useful.

The intention is and always has been to build a platform that would make open initiatives — such as OSM — more accessible to the general public. I would love to hear your thoughts and see if we can turn our work into something that's valuable to OSM.

I'm not saying that where anywhere near ready to "compete" with GitHub on a feature level, but we would be very happy to build whatever serves you best!

A couple questions to get the conversation started:

1. Why would (or wouldn't) such a platform be useful? 🤔
2. If you could wave a magic wand and change GitHub in any way you wanted, how would you change it? 🧙✨

Cheers,
Finn

[MedChemProf]

Honestly, I have never found GitHub particularly attractive as a platform to host a collaborative research project such as the OSM. I understand all of the reasons for which it was chosen and it is functional, but as a participant in the OSM I have found trying to follow the discussion currents very frustrating. Much of the problem may simply be my lack of experience in navigating GitHub, but the below listed items are a summary of some of my issues. Many of these might be irrelevant with more time and training, but time is something I do not have to devote to a task that should be intuitive.

1. The Search feature of GitHub does not seem to be effective. My searches have largely had me going in circles without finding the thread of discussion that I was looking for. This is true even when I try and stay within the OSM project.
2. The Issues / Discussion Threads are not well organized, tagged or labeled. A newcomer or even someone just not familiar with a particular issue may not be able to find that topic or even if it was already discussed. New students joining my lab have no idea how to navigate to find some of the basic lines of discussion.
3. Data management. Again, this is probably my fault for only being able to devote my time to the project periodically, but I always seem to have to reinvent the wheel to try and find the most current set of data. Even when I find the data spreadsheets, I am not certain if they are in fact the most up to date.

Thank you for letting me vent some of my frustrations. I believe in the premise and promise of the OSM and I am more than familiar with the issues of trying to fund / support basic research. I cannot say enough about how impressed I am with @mattodd for his organizational prowess and drive in keeping the project going. All of my comments were aimed at GitHub and not the OSM.

[holeung]

I also find github difficult to use. I share many of the same specific complaints as @MedChemProf. I've been using the OSM Github for about two years now, and I still get confused about how to find information. I feel that Github is fine for managing code-based projects and for people used to git, but it feels awkward for OSM. On the other hand, I am not familiar with better alternatives. Whatever platform we adopt should be easy to learn and use for students, especially those from a biology or chemistry background.

[drc007]

@FinnWoelm I've had to use use many different document management systems when working with different groups, including GitHub, Drupal, Joomla, Dotmatics, Intralinks, Box, Pandadoc, Huddle, CDD, Science Cloud. None are ideal, all have their quirks and all have a learning curve. If you want the system to be open-source then there are limited options. If you want to do Open Source science then shouldn't the software also be open-source?

Searching and indexing is an issue, you need to be able to search message threads, all document types (pdf, text, presentation, spreadsheet, chemical structure etc.). It would be better if the indexing recognised molecule identifiers. Simply hoping that Google will do the indexing is not enough.

It also requires some discipline by the users to tag documents/messages appropriately but this is very difficult to enforce. One of the quirks of GitHub is that closed issues are not visible by default, this makes sense when tracking code bugs but does not help newcomers.

Ideally all the meta data for every assay would be accessible.

In an ideal world all current data would be in a sub-structure searchable database with a web interface. With business rules defined that control multiple results from the same assay, run on different batches, run in different labs etc. With the ability to export to desktop for analysis.

[mattodd]

This is super useful feedback, thanks for taking the time. A few quick observations around why I think this platform currently beats many potential others:

1. I've always found the search function to be pretty good. I like that search covers closed issues, and I like that links to closed issues remain active.
2. I like that we can link discussions easily by include hashed numbers.
3. I find the wiki relatively easy to use
4. I note that people who are often tech-phobic are happy to come on here and get started.
5. Github is non-spammy with email.
6. Dragging pictures onto issues as a way of sharing them is simple.

Obviously there are things that need to be better, and many of those are in comments above. The filestore works well for anyone running the desktop client, but for everyone else I imagine it's sub-optimal. Something more like Dropbox would, I suspect, be useful.

That Issues are linear discussions, without threads (branching out), can sometimes make things difficult to follow.

In some cases the difficulty of following things might be an inevitable result of things being busy and there being nobody available to collate the discussion into action items and close the relevant issue. No platform will solve that - it's a different problem. Your point @MedChemProf about the most up to date datasheets is I think something more about how we maintain lab books and other components, rather than Github?

From our point of view a platform that understands chemistry would obviously be amazing. I mention this in talks every now and again, that we need a way of referring to a molecule like an issue number - e.g. "IDENTIFIER-X" is linked to a row in the Master List, for example, so that the page understands which molecule you're referring to in the way that it can currently understand if you're referring to another issue.

A big thing for me is to make the "suggest change-review change-accept change" cycle easier to understand. This function is ultimately fundamental to how we work as scientists. We look at things, we suggest changes and people accept or reject those changes. This feature is at the core of Github. Yet we're not using it properly. Over at Google Docs etc we all use such a thing. We read and suggest/comment and those suggestions are accepted or not. We need this functionality to be easier across Github issues, files and wikis.

[bendndi]

@FinnWoelm I'm just going to jump in here quickly to make a suggestion for a simple change to github. If it were possible to upload and share sdf files (.sdf) on Github, this would, I think, go a long way to making it a more attractive tool for open science work. Unfortunately it is currently not a recognised file format and so is not permitted.
This would not be as cool as having a fully shareable open DB (e.g. sciencecloud but fully open), but in theory would be a hell of a lot easier and quicker to implement, and for "smaller"(< 500 compounds) projects could in theory replicate most of the functionality of an open data base. It would just be a case of having a master sd file which was available and constantly updated whenever new data comes in. Similar to the excel / spreadsheets used currently by OSM and mycetos, but with much greater functionality and chemically aware.

[FinnWoelm]

@MedChemProf , @holeung , @drc007 , @mattodd , @bendndi — thank you all for sharing your thoughts!

Apologies for the delayed reply. I quickly realized that this would become a challenging conversation for me, given my lack of a bio/chem background. 😅 This weekend, I finally got a chance to set aside some time and really dive in. Thanks for your patience.

---

🔍 Search

My searches have largely had me going in circles without finding the thread of discussion that I was looking for. - @MedChemProf

Can you share a little more about that?

Is the issue that GitHub does not search for similar/related words? For example: If I search for improve, then this thread shows up. If I search for improvement or improv, this thread does not show up. Or is it that it's unclear which repository the conversation happened in (to do list vs series 4) and thus unclear where to search? Or is it something entirely different?

Do you maybe have a specific example of the last time this happened?

Searching and indexing is an issue, you need to be able to search message threads, all document types (pdf, text, presentation, spreadsheet, chemical structure etc.) - @drc007

Yup, rich text indexing is definitely a challenge with GitHub. The chemical structure files you are referring to, are those the .cdx and .cdxml files?

👩‍🎓 Students

New students joining my lab have no idea how to navigate to find some of the basic lines of discussion. - @MedChemProf

Whatever platform we adopt should be easy to learn and use for students, especially those from a biology or chemistry background. - @holeung

How do you usually solve this issue with your students? Do you walk them through the core features of GitHub? Do you have a video/text/interactive tutorial you send them? How do they respond to that: Do you lose their interest in the process or are they eager to contribute and participate once they "get it"?

☁️ Open Web Database

In an ideal world all current data would be in a sub-structure searchable database with a web interface. - @drc007

Probably outing myself as a complete newbie here 🙈, but isn't OSM's Molecule Database sort of like that?

🔬 Molecule References

[W]e need a way of referring to a molecule like an issue number - e.g. "IDENTIFIER-X" is linked to a row in the Master List, for example, so that the page understands which molecule you're referring to. - @mattodd

What's the benefit of having "the page [understand] which molecule you're referring to"? So that you can easily find all conversations related to a molecule while browsing the master sheet? It's like doing a search for OSM-E-32, OSM-S-265, or similar, but without having to manually run the search? Curious to learn more!

⬆️ Sharing SDF files

If it were possible to upload and share sdf files (.sdf) on Github, this would, I think, go a long way. - @bendndi

Are you referring to attaching SDF files to a discussion (such as this)? Or is it about uploading it to a GitHub repository? Because it's definitely possible to upload it to a GitHub repository!

In fact, I found this OSM repo that was using SDF to track compounds about 6 years ago. And I see that it's hosted remotely now as of Series 4. Looks like it was decided that Google sheets would replace SDF as the primary data source?

📂 File Organization/Structure

I always seem to have to reinvent the wheel to try and find the most current set of data. Even when I find the data spreadsheets, I am not certain if they are in fact the most up to date. - @MedChemProf

What would make the most current set of data easier to find? What would make it clear whether it's current? Prominently displaying a link to it somewhere on the website or in the GitHub readme?

Your point @MedChemProf about the most up to date datasheets is I think something more about how we maintain lab books and other components, rather than Github? - @mattodd

This does indeed go somewhat away from the Q about GitHub — but I'm very curious. As far as I can tell, these are the main collaboration/communication tools in use:

• 📋 Google Sheets: Master List
  This Google Sheet is the master list of molecules. It feeds into the molecule database on cheminfo.org.

• ☑️ GitHub: OSM To-Do List
  This GitHub repository is used to track issues. No files. No wiki.

• 📖 GitHub: Series 3 and Series 4
  These repositories are used as a wiki. To make changes to the wiki, you need to be a collaborator of OSM.
  There are files in the repo, but they are exclusively primarily used as attachments for the pages in the wiki. How do you determine/decide what makes it into the wiki?
  There are some issues/discussions in these repo, too. Unlike the issues in the OSM To-Do List, these issues are specific to the series?

• 📓 Electronic Lab Notebooks
  The core contributors maintain ELNs. These are hosted in various places and with various software.

Is this accurate? What led to the adoption of Google Sheets (over, for example, a CSV file in GitHub)? Doesn't this a) make searching more difficult because data is in multiple platforms, b) make contributing more difficult because the Google sheet defaults to view-only permission for non-contributors, and c) make tracking changes more difficult because there's no "git log"?

🚥 Workflow

A big thing for me is to make the "suggest change-review change-accept change" cycle easier to understand. - @mattodd

Can you tell me more about that? As far as I can tell, OSM is not using GitHub's pull request workflow (series 3 had no PRs and series 4 had four PRs). Instead, users are added as collaborators to the repository and the Google sheet to receive direct edit access, yes? Is that because PRs are too complex or because PRs are not useful?

💬 Threaded Discussions

That Issues are linear discussions, without threads (branching out), can sometimes make things difficult to follow. - @mattodd

As I'm writing this, I could not agree more 😀

[drc007]

@FinnWoelm Chemical structure files can be many different forms. cdx is a proprietary binary data format that can contain chemical structure information, but also display, text, tables, arrows, boxes etc. cdxml is is the xml version. The are many, many other chemistry file formats OpenBabel (http://openbabel.org/wiki/Main_Page) has details of over 100 file formats. Most contain chemical structure and meta data in a fully defined format. However whilst most are text based, viewing the contents in a understandable format usually requires a special reader.
You will also hear mention of SMILES strings (http://www.daylight.com/smiles/index.html) this is a way of encoding chemical information into a linear text string. It is a very compact and efficient way of storing chemical structures, and whilst human-readable, it is not necessarily human-interpretable. In an ideal world a search engine would allow the user to find a specific SMILES string in a web page or even structure-based searches.
Whilst not really a file format InChi are generated from a chemical structures to provide a unique identifier specific for that given structure. (https://en.wikipedia.org/wiki/International_Chemical_Identifier). The condensed, 27 character InChIKey is a hashed version of the full InChI (using the SHA-256 algorithm), designed to allow for easy web searches of chemical compounds.

[drc007]

@FinnWoelm Google sheets versus sdf as repository.
Whilst the sdf format is a good way to combine, store and share chemical structures it is not a format that can easily be edited using a text editor, it requires specialist software. Since we wanted to encourage as many people as possible to contribute many of whom have little background in chemistry we moved to using a spreadsheet format (google sheets) that does not require the user to have access to any specialist software. People seem pretty comfortable using a spreadsheet, however we do recognise it has many limitations with respect to a modern relational database. The Google sheet does allow programatic access (for example using Python which means expert users can import it into a desktop application of their choice.

The OSM's Molecule Database is another example of pulling data from the Google sheet. It does not allow users to enter data into the database directly. Whilst it allows substructure searching you can't currently combine structure and alphanumeric searches. I'm also not sure how easy it would be to implement a relational database since it currently imports from effectively a flat file.
A proper relational database with a web front-end remains on the todo list.

[cdsouthan]

Having seen demos of CDD and Stardrop in Copenhagen this week I suggest the OSM project team should get quotes for both. No idea how finances are/will be run from UCL and/or USYD for 2019 so maybe an explainer would be useful

Update: n.b. I checked with them about exporting data which they said should be no problem (i.e. closed > open). If there is any interest (anyone can hit the free trial) in my capacity as SAB member I can discuss more with them about "opening up" options since there are certainly other OSDD teams who would like to take advantage of the data organisation but also want to work in the open

[drc007]

I guess one question might be should an Open Source project be funding closed source software?

[drc007]

@FinnWoelm Another nice to have is a easy way to display proteins/structures etc. there are number Javascript viewers but they all require some experience with javascript coding.

Examples would be 3Dmol.js http://3dmol.csb.pitt.edu/index.html or NGLviewer http://nglviewer.org

[drc007]

There are alternatives

…

On 31 Mar 2019, at 10:11, cdsouthan ***@***.***> wrote: I guess one question might be should an Open Source project be funding closed source software? but Microsoft and ChemDraw? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#580 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGwKRHgj0FTkklVwQaZ8bo2RQapTkQo-ks5vcHutgaJpZM4benwc>.

[cdsouthan]

@FinnWoelm Another nice to have is a easy way to display proteins/structures etc. there are number Javascript viewers but they all require some experience with javascript coding.

Examples would be 3Dmol.js http://3dmol.csb.pitt.edu/index.html or NGLviewer http://nglviewer.org

Try EzMol - http://www.sbg.bio.ic.ac.uk/ezmol/ a web-based, wizard-drive, molecular graphics display. It is designed for the occasional user who does not wish to invest the time to use programs such as PyMol and Chimera. Generated images can be downloaded for publication. It’s a bit like EasyJet – basic but gets you from A to B. (See Reynolds, et al (2018). JMB)

[drc007]

EzMol is built using 3Dmol.js, it is a nice implementation but I don't think you can embed the resulting structure file within the OSM website, just a static image. You can download a .ezm file but then need to go to the EzMol website to view it. Would be better if it could export the javascript code used to generate the display.

[drc007]

Something like this, another site I'm working
https://opensourceantibiotics.github.io/murligase/373.html

[mattodd]

Very nice summary of things we're using, Finn! Lots of discussion here, and perhaps the reason it's stalled is that there's too much to take in. @FinnWoelm is there something you'd like to tackle, specifically, and we could bud off to a new Issue to tackle something? Depends on your bandwidth.

Three quick things:

1. The "suggest change-review change-accept change" cycle. I'm thinking about the wiki, which is not maintained communally, really. And I'm thinking about file uploads. It'd be good if people could make changes and as part of that process have the changes verified as a way of quality control. Ironically this check and balance might make people more likely to suggest changes since they know that errors would get picked up.

2. Molecule identifiers - yes, a way to find all the instances that we discuss a particular molecule. Not sure of the best way to do that. We can't rely on people including perfect codes (e.g. OSM-S-250) each time, since we don't write in that way. All the identifying data associated with a molecule (its synonyms) are in the Master List. We needn't have all the data again here, but if we had a way of tagging that we were discussing a particular molecule, that'd be really handy, and then one can imagine it being a lot easier to find conversations that are relevant to each other. Could you not then imagine there being a page for each molecule that lists each page where the molecule is discussed? We built that manually in the early days of OSM. Nightmarishly hard (and it therefore eventually failed) but super useful.

3. @bendndi and I have been speculating idly that a repo of Github itself might do a pretty good job of being an electronic lab notebook. i.e. people could post experiments as issues, upload data to the repo, assimilate findings in the wiki and so on. It'd be fun to try that out, and we might have a go, to see what works.

(FYI have linked this discussion here)

[cdsouthan]

Use the InChIKey as the molecuar identifier

[drc007]

Use the InChIKey as the identifier

Strictly speaking InChiKeys are not unique.

They are also not particularly human friendly, ATALOFNDEOCMKK-OITMNORJSA-N is not particularly memorable and easy to make errors whilst typing. Another useful feature of using something like OSM-000123 is that a table sort puts the molecules into chronological order.

[cdsouthan]

I seem to remember the suggestion of OSM000123 (sans hyphen -puleeze...) came up ages ago. The trouble with adding anything at this stage (human-friendly or not) is it just makes the retro-mapping-spaghetti problem worse with each new identifier or synonym

[drc007]

Which is why you have to decide at the start of a project

[cdsouthan]

Amen

[spirobel]

@MedChemProf , @holeung , @drc007 , @mattodd , @bendndi — thank you all for sharing your thoughts!

Apologies for the delayed reply. I quickly realized that this would become a challenging conversation for me, given my lack of a bio/chem background. sweat_smile This weekend, I finally got a chance to set aside some time and really dive in. Thanks for your patience.

mag Search

My searches have largely had me going in circles without finding the thread of discussion that I was looking for. - @MedChemProf

Can you share a little more about that?

Is the issue that GitHub does not search for similar/related words? For example: If I search for improve, then this thread shows up. If I search for improvement or improv, this thread does not show up. Or is it that it's unclear which repository the conversation happened in (to do list vs series 4) and thus unclear where to search? Or is it something entirely different?

Do you maybe have a specific example of the last time this happened?

Searching and indexing is an issue, you need to be able to search message threads, all document types (pdf, text, presentation, spreadsheet, chemical structure etc.) - @drc007

Yup, rich text indexing is definitely a challenge with GitHub. The chemical structure files you are referring to, are those the .cdx and .cdxml files?

woman_student Students

New students joining my lab have no idea how to navigate to find some of the basic lines of discussion. - @MedChemProf

Whatever platform we adopt should be easy to learn and use for students, especially those from a biology or chemistry background. - @holeung

How do you usually solve this issue with your students? Do you walk them through the core features of GitHub? Do you have a video/text/interactive tutorial you send them? How do they respond to that: Do you lose their interest in the process or are they eager to contribute and participate once they "get it"?

cloud Open Web Database

In an ideal world all current data would be in a sub-structure searchable database with a web interface. - @drc007

Probably outing myself as a complete newbie here see_no_evil, but isn't OSM's Molecule Database sort of like that?

microscope Molecule References

[W]e need a way of referring to a molecule like an issue number - e.g. "IDENTIFIER-X" is linked to a row in the Master List, for example, so that the page understands which molecule you're referring to. - @mattodd

What's the benefit of having "the page [understand] which molecule you're referring to"? So that you can easily find all conversations related to a molecule while browsing the master sheet? It's like doing a search for OSM-E-32, OSM-S-265, or similar, but without having to manually run the search? Curious to learn more!

arrow_up Sharing SDF files

If it were possible to upload and share sdf files (.sdf) on Github, this would, I think, go a long way. - @bendndi

Are you referring to attaching SDF files to a discussion (such as this)? Or is it about uploading it to a GitHub repository? Because it's definitely possible to upload it to a GitHub repository!

In fact, I found this OSM repo that was using SDF to track compounds about 6 years ago. And I see that it's hosted remotely now as of Series 4. Looks like it was decided that Google sheets would replace SDF as the primary data source?

open_file_folder File Organization/Structure

I always seem to have to reinvent the wheel to try and find the most current set of data. Even when I find the data spreadsheets, I am not certain if they are in fact the most up to date. - @MedChemProf

What would make the most current set of data easier to find? What would make it clear whether it's current? Prominently displaying a link to it somewhere on the website or in the GitHub readme?

Your point @MedChemProf about the most up to date datasheets is I think something more about how we maintain lab books and other components, rather than Github? - @mattodd

This does indeed go somewhat away from the Q about GitHub — but I'm very curious. As far as I can tell, these are the main collaboration/communication tools in use:

* clipboard **Google Sheets: [Master List](https://docs.google.com/spreadsheets/d/1Rvy6OiM291d1GN_cyT6eSw_C3lSuJ1jaR7AJa8hgGsc/edit#gid=510297618)**
  This Google Sheet is the master list of molecules. It feeds into [the molecule database on cheminfo.org](http://www.cheminfo.org/flavor/malaria/Utilities/Substructure_search.html?viewURL=http%3A%2F%2Fcouch.cheminfo.org%2Fcheminfo%2Fe7ec823f14daf7223e7e77261e8ba5af%2Fview.json%3Frev%3D5-ccb988ca09471e979580be7093acb42d).

* ballot_box_with_check **GitHub: [OSM To-Do List](https://github.com/OpenSourceMalaria/OSM_To_Do_List)**
  This GitHub repository is used to track issues. No files. No wiki.

* book **GitHub: [Series 3](https://github.com/OpenSourceMalaria/Series3) and [Series 4](https://github.com/OpenSourceMalaria/Series4)**
  These repositories are used as a wiki. To make changes to the wiki, you need to be a collaborator of OSM.
  There are files in the repo, but they are ~exclusively~ primarily used as attachments for the pages in the wiki. How do you determine/decide what makes it into the wiki?
  There are some issues/discussions in these repo, too. Unlike the issues in the OSM To-Do List, these issues are specific to the series?

* notebook **Electronic Lab Notebooks**
  [The core contributors maintain ELNs](https://github.com/OpenSourceMalaria/Series4/wiki/Sources-of-Data#lab-notebooks). These are hosted in various places and with various software.

Is this accurate? What led to the adoption of Google Sheets (over, for example, a CSV file in GitHub)? Doesn't this a) make searching more difficult because data is in multiple platforms, b) make contributing more difficult because the Google sheet defaults to view-only permission for non-contributors, and c) make tracking changes more difficult because there's no "git log"?

traffic_light Workflow

A big thing for me is to make the "suggest change-review change-accept change" cycle easier to understand. - @mattodd

Can you tell me more about that? As far as I can tell, OSM is not using GitHub's pull request workflow (series 3 had no PRs and series 4 had four PRs). Instead, users are added as collaborators to the repository and the Google sheet to receive direct edit access, yes? Is that because PRs are too complex or because PRs are not useful?

speech_balloon Threaded Discussions

That Issues are linear discussions, without threads (branching out), can sometimes make things difficult to follow. - @mattodd

As I'm writing this, I could not agree more grinning

I think many of the issues could be solved with discourse. For example threaded discussions. Also I think some universities already use it to deal with students
https://meta.discourse.org/t/how-to-convince-my-university-to-use-install-discourse/63882

If you are interested I could help install a discourse instance. Then we can start to figure out which parts of it need to be modified so it suits your needs.

https://docs.google.com/spreadsheets/d/1Rvy6OiM291d1GN_cyT6eSw_C3lSuJ1jaR7AJa8hgGsc/edit#gid=510297618

I seem to remember the suggestion of OSM000123 (sans hyphen -puleeze...) came up ages ago. The trouble with adding anything at this stage (human-friendly or not) is it just makes the retro-mapping-spaghetti problem worse with each new identifier or synonym

I think the only true way to solve this problem is to have a database that is coupled with your labnotes and discussion board. I explained in this issue how we might achieve this:
#581 (comment)