As some of you may know, I am in the process of trying to bolster even further JuliaHealth membership and participation. A question I had for other Julia organizations is how do you handle logistics like sharing meeting notes, organization documents, and other content within the organization that is either more logistical or org-specific in nature? I have been currently hosting meeting notes on my own personal Google Drive but that feels a bit untenable (in the sense of being on one person’s account) and I want to make sure that if something happens to me, there is continuation or those pieces of information are available.
So, orgs, how do you handle this? Pinging @gdalle@vchuravy@carstenbauer and @jakobnissen for some thoughts on this as well since you all do excellent within your orgs (it seems to me at least!)!
I’m halfway kidding, but I don’t think BioJulia is a particularly well-run organisation to be honest. The current set of maintainers (myself included) just kind of stumbled into inheriting it from the previous set of people such as Ben Ward and Kenta Sato (and before that: Joe Greener? Maybe also others).
We don’t keep discussions anywhere in particular. It’s kind of spread all over and it appears some are lost. We recently accidentally forgot to update our website domain name so had to change it. Half of our packages are in a broken state because there are too few maintainers.
So yeah, don’t copy us
That being said, I at least have learned some lessons:
Structure your org so that it does not depend on specific people to stay around: All repos and shared documents must have write access by multiple people.
Don’t make promises about what people can deliver when (e.g. package updates or new packages): It has worked out poorly the few times we’ve done it.
Structure your packages to last, since maintenance is going to be a big issue: Avoid fancy new Julia packages with e.g. complex macros, or that hook into the compiler, as they tend to change a lot. Avoid too platform-specific solutions, if possible. Make code inferrible. Be vigilant of their dependencies.
Make some effort recruiting people who seem interested: Guide them through their first few PRs. A few of these people might end up contributing massively.
Amen to that. JuliaGraphs is a great project full of great people, but my feeling is that development happens in individual sprints rather than coordinated efforts. When one of us has time, a few PRs get merged, a few issues get closed, and then the project goes back to sleep for a while.
And sometimes, an unsung hero like @etienne_dg starts reinventing the whole ecosystem, which is sorely needed but not something that is easy to do with a team of overstretched people on several continents.
I agree with Jakob’s lessons, and I would add some more from my own experience and mistakes:
GitHub issues are a good way to structure work and lay out roadmaps, but there are too many of them. It can be useful to structure and prioritize them, either with tags or within a GitHub project.
In an organization with very little maintainer time, when one person is available to work on something, the temptation is strong to merge right away, cause otherwise the process can take weeks. I have often found myself greedily merging PRs, only for @simonschoelly to rightfully point out that more discussion would have been necessary. To circumvent these tensions, I find myself needing a set of clear organization-level guidelines on how many reviews / approvals / likes are needed before acting, how much time to wait for these reactions, etc.
On a related note, more communication within the organization can never hurt. Currently our day-to-day exchanges (really month-to-month) go through a Slack channel and get swallowed by the void. It would be awesome to have Zoom calls to discuss triage or long-term package orientation. And getting to know each other better would also foster a sense of community.
In an organization with very little maintainer time, when one person is available to work on something, the temptation is strong to merge right away, cause otherwise the process can take weeks. I have often found myself greedily merging PRs, only for @simonschoelly to rightfully point out that more discussion would have been necessary. To circumvent these tensions, I find myself needing a set of clear organization-level guidelines on how many reviews / approvals / likes are needed before acting, how much time to wait for these reactions, etc.
This is a bit off tangent to the OP here, but - subjectively - I feel that more greedy merging of PRs would be very welcome in the Graphs ecosystem. While caution and thoroughness are important, I think - at this stage in the ecosystem, at least - the main risk is lack of development (and hence, lack also of maintainers and eventually relevance). In that sense, showing that contributions can and do get merged without months-long and intermittent optimization is more important than caution; further iteration on contributions can always occur over follow-up PRs potentially.
If the fear is shipping suboptimal new features or designs, it could still be guarded by just releasing new versions to the registry more rarely.
Right now, I would guess that the Graphs ecosystem sees less contributions than it could, because anyone looking at the PR queue or merge activity will assume a new PR will be slow to/may not merge.
From my perspective, empowering current maintainers to merge more readily would be great.
I agree. It’s better to keep moving than staying idle. I believe practically this leads to a net positive. Otherwise we are getting consumed by inertia and the overhead of static friction.
Having a platform is also important. Slack is totally incapable of supporting a whole julia org. Bad code formatting and a single unstructured channel for the whole org to dump their messages into is not ideal. Not to mention the slackhole. We could spend months searching for the next ultra productive platform, months for setting it up and months for adapting it. Or we can start switching to zulip tomorrow, which already has an active julia community and a graphs stream waiting to be used.
First, to speak on a general level, I fully agree with @tchr and and @filchristou with the sentiment of merging earlier rather than later. In fact, I would say I am one of the greediest of mergers. Sometimes this makes me rather embarassed of myself, and some other times it leads to huge regrets like having to rewrite an API. But on average it is a clear net positive.
Specifically now on my experience with JuliaDynamics. I think it is safe for me to say that the org has done very well in terms of management: the org is largely self-organized, which means that there is no central intelligence that coordinates all packages. (and this ties very well with the org’s theme which gives me a big smile!). Concretely, this means that there are hubs of content that are coordinated individually, e.g., discrete event based simulations, agent based modelling, finding attractors, etc. Each such “hub” has some dedicated devs that co-ordinate on GitHub directly, also without a central intelligence to coordinate things. Although, I should say, I can say for sure that at least two packages have a “lead developer” that coordinates coordinates things (which is me), but again this is not 100% in the sense that I don’t have to review all PRs and I do not merge all PRs, others do so as well. Here’s the things I personally value and believe yield simple and effective management:
source code simplicity. This has nothing to do with management yet makes it so much simpler. Designing new APIs, finding out the issues with current APIs, maintainance, motivating/enabling new contributions, review PRs. All of this becomes easier when attention to the simplicity of both the design and the implementation has been put together.
When reviewing, spend the majority of your time on design. This enables the above point. I typically spend about 70-80% of my review time on just the design, the input-output arguments and their logical connection, and the documentation. Just 20% on code and performance.
Review some PRs intensely, but not all. Some PRs may have a large library-wide impact. Some not. Most not. Think of which do not have a big impact (typically new features that ar eindependent of everything else, or bug fixes) and review them as greedily as possible. Bug fixes come later easily. Also, I tend to “trust” quite a bit frequent contributors and always review their PRs more lightly than a new comer. I always review newcomer PRs intensely not just because I have no knowledge of their skills yet, but more importantly, because a newcome is more likely to need my guidance to improve her/his skills via the PR.
Do live meetings only when necessary and otherwise coordinate on GitHub issues. Look, I am a huge fan of live meetings. In the projects I am part of, when there is a large topic to be discussed, I will often invite the co-developers in an online meeting or something. But there is no fixed or recurrent meetings, we will only meet if there is a special topic to meet for. And, nevertheless, I strongly believe that everything that matters for a package should be written in the packages Issue page. (And not spread discussions among other places like GitHub discussions, GitHub wikis, google share documents, whatever). This also promotes openeness (see below)
Be open and inviteful. I actively invite people to the org and tell them in advance how management is done: they get admin-level rights to a GitHub team with all their repos and that’s it. And when someone contacts me in joining the org, as long as the subject is related with the org theme, I am like “hell yeah!”.
As I’ve stated many times, the role of the org JuliaDynamics is much more so for discoverability than it is for management. This has pros and cons of course! I’m happy to share more experiences if you have questions about this somewhat different approach!
oh forgot to say that I’ve also used GitHub projects for all major changes in libraries I’ve done so far. They are incredible, incredibly useful as well!
One piece of contrary evidence that I already mentioned on this forum. The function for removing a collection of nodes from SimpleGraph (the only well-supported implementation of a graph) was merged with insufficient review. ​And the API has this inefficiency baked in.
To be fair, if you follow the link, you see that the review was more careful than most. I don’t know what would have prevented letting the complexity leak into the API. I’ve seen worse happen in OSS projects with an army of paid workers. I think they rely on a lot of use in the wild before a release.
It’s not the end of the world; we can introduce a new function with a new name and deprecate the old one without removing it until/if 2.0 is released.
Of course the best course depends on the details. There is a lot of room between just clicking “merge” and an elaborate formal process.
EDIT: what may help in cases like the one in this comment is one of the points from @Datseris
When reviewing, spend the majority of your time on design. This enables the above point. I typically spend about 70-80% of my review time on just the design, the input-output arguments and their logical connection, and the documentation. Just 20% on code and performance.
I took a few days to digest this information but I wanted to share my summarization of all the thoughts here so far! Please let me know if I missed anything; either way, this will be a talking point for future JuliaHealth meet-ups so thank you all so much for the commentary! Here is the outline:
Structure Organization for Sustainability
Limit dependency on any one person – Jakob Nissen, George Datseris
All repositories and shared documents should have write access for multiple people, ensuring continuity even if some contributors are unavailable – Jakob Nissen, Guillaume Dalle
Furthermore, packages should be designed with longevity in mind, as maintenance can be a significant challenge – Jakob Nissen, Georgia Datseris
Build trust with frequent contributors – George Datseris
Could review their PRs more leniently
Provide detailed reviews for newcomers
Organization Guidelines
Think about what is the criteria (such as reviews or approvals) before action on a pull request is taken – Guillaume Dalle
Setting clear timeframes for feedback should be established – Guillaume Dalle
Allocate review time (around 70-80%) to evaluating design aspects, logical connections between input-output arguments, and documentation of features – George Datseris
Adapt the intensity of a PR review based on its potential impact to a package – George Datseris
PRs with package wide consequences should receive thorough evaluations
PRs that are independent of existing code could be reviewed more quickly
Bug fixes that affect small parts of the package could be reviewed faster
Managing Package Development
Use GitHub issues to outline development roadmaps for a given package – Guillaume Dalle
Use labels to prioritize GitHub issues as important and relevant to a given package – Guillaume Dalle
Prioritize discussions within GitHub issues to foster transparency and consolidate discussions in location – George Datseris
Maintain source code simplicity – George Datseris
Community Outreach and Communication
Avoid making promises about deliverables or timelines – Jakob Nissen
Community calls for triage discussions or long-term package orientation can help build community – Guillaume Dalle
Actively invite individuals to join the organization – George Datseris
Provide them with administrative rights to relevant GitHub teams and repositories to foster participation
Hopefully this could be a useful reference for future Julia or otherwise open source organizations!
Just checking back to give a nice little quick update! We had our monthly community call and made the decision to publicly host our meeting notes here for JuliaHealth: JuliaHealth - Meeting Notes and our raw notes are here: JuliaHealth Meeting Notes - HackMD
Additionally, we are using HackMD to make the entire process far easier to collaborate and push to the repository. It is ridiculously easy as our website uses Franklin and each push makes the website automatically rebuild and HackMD has great integration support with GitHub repositories. So easy in fact, that we can just click push within HackMD at the end of a meeting and our notes get automatically published. Pretty outstanding and I highly recommend the tool!
This is built upon the advice y’all gave here and we wanted to make our notes as public as possible – thanks again everyone!
Hi folks! Resurrecting this thread that I asked about but does anyone here have experience using GitHub projects for project management of your Julia organization? Or do you use something else to manage ongoing overarching projects across your organization?
This is a great place to link to Chris’ recent talk on maintaining large Julia ecosystems. It doesn’t talk much about project management, but it’s well worth a watch:
. We’re trying, but not succeeding all that well.
