OpenCraft Core Contributors Call for Proposals: Summit to Enhance the Core Contributor Experience

Hi :slight_smile: @jill @Agrendalath @kshitij @gabriel @Ali @mtyaka @pooja @farhaan @antoviaque @cassie @navin @gabor @braden @ChrisChV

OpenCraft Core Contributors will be taking part in a Summit to Enhance the Core Contributor Experience.

What’s it all about?

This summit aims to gather innovative ideas and actionable proposals to address the key challenges identified in the Improving the core Contributor Experience report. We’re looking for solutions that will help us improve the overall experience of our Open edX Core Contributor Program, making involvement more efficient and impactful.

View detailed information about the summit here.

How do I start?

This thread is to brainstorm ideas for each of the 4 topics mentioned:

  1. Enhance Core Contributor Onboarding
  2. Improve Collaboration, Communication & Reporting
  3. Improve Fulfilling Commitments and Planning Processes
  4. Improve Review Processes

Please share any ideas you have so we can build a big list. We’ll pick the best ones to submit as proposals.

When do I need to submit my proposal?

Proposals need to be submitted on the Oct 6, 2024. Watch this space for updates of how to submit. So it’s a tight deadline!

When do I need to present my proposal?

All proposals will need to be presented at a virtual summit on Oct 21, 2024. Watch this space for updates.

Where do I log my time?

Please create relevant tickets and allocate applicable Core Contributor hours to cover your participation. Please ensure Xavier is the second reviewer on your proposal tickets.

Looking forward to seeing everyone’s ideas! :sunflower:

4 Likes

Here are some of my thoughts:

Topic 1: Improve the Core Contributor Onboarding Experience

  • Create a comprehensive “handbook” for Core Contributors, to be used during onboarding and throughout their tenure. This guide should include onboarding procedures, processes, tools, role-specific information / links, communication expectations, contact persons for each role category, and more. Move existing information to a new Wiki space and expand on it there.The handbook will serve as a detailed reference for daily situations, while the onboarding course will cover introductory information. To prevent duplication, the onboarding course should link to relevant sections of the handbook for more details. Here’s our Handbook as an example.

Topic 2: Improve Collaboration, Communication & Reporting

  • Review the current list of active working groups and ensure all the working groups that Core Contributors participate in are mentioned and defined - view the survey data (this can be defined within the Handbook described in Topic 1).
  • Ensure that Working Group names are self-explanatory and consistent across all tools (e.g., Working Group Calendar, Wiki). For example, use “Contributor Coordination Working Group” consistently (this can be defined within the Handbook described in Topic 1).
  • Evaluate and define communication tool roles to reduce complexity and reliance on synchronous communication. The top 5 communication tools are the Discussion Forum, Slack, GitHub, Atlassian Wiki, and the Open edX Blog, with the Discussion Forum being the most preferred. To improve communication, we could use the Forum more for announcements like Product Proposal Requests and reviews, which are often missed in Slack (78.9% of people suggested merging communication tools, and 60% find Slack’s synchronous nature problematic), particularly across different time zones (importantly, open source projects thrive on public conversations). Keep in mind that preferences will vary by role; for instance, engineers may prioritize GitHub, while translators might rank it lower.
  • Merge the Contributors Meetup Async Update and the Core Contributor Check-in into one report. To enhance communication, transparency, and collaboration the report should provide a snapshot of essential information, minimizing the need for members to search across forums, Slack, and Wiki. By focusing on valuable content we can streamline information distribution. The report should feature TL;DR summaries, links to project roadmaps, relevant blogs, release updates, open forum posts needing input, categorized PRs, and involvement opportunities. Content should be tailored based on the Listaflow community questionnaire feedback to ensure relevance. Distributing the report through Slack and email notifications, with forum comments for contextual feedback, will enhance its reach and effectiveness. This approach aims to improve communication by making updates more accessible and transparent, thereby fostering better engagement and collaboration. The report could be less frequently posted than the current Contributors Meetup Async Updates and the Core Contributor Check-ins, to minimise administrative overhead.
  • Streamline the Listaflow questionnaire based on the results of the survey. Ensure its purpose and value is clear.
2 Likes

@cassie Thanks for putting this all together, and for arranging the summit. :slightly_smiling_face:

I think CC’s would find this useful, especially when they first join the programme. It would also allow us to describe some of the items people were confused about e.g. how sprints work, which communication tool to use when, the purpose of Listaflow checkins etc.

I like this idea in theory, but I’m not sure how many CCs would actually take the time to read the report, even if we make it more digestible. I expect it would require a lot of effort to compile, and I suspect (though I could be wrong) that only the most dedicated CCs would read it. This stood out for me from your summary:

Issues with the questionnaire’s length and perceived value were highlighted by responses. Mixed responses on its usefulness, with some finding it valuable and others seeing it as burdensome.

In your other doc, you mentioned the option of using a Discourse Newsletter Plugin. I wonder if an approach like this, or perhaps improving the Listaflow reports so that we could use them instead, might make more sense.

Thanks @Ali :slight_smile: I agree and would like to take this on. @antoviaque are you happy for me to take on this proposal?

I see your point. I’m also worried about this. I think there must be something simple we can do that can show people what’s being worked on, where they can find work etc to encourage more transparency and collaboration Perhaps we need to leverage GitHub better. I also think a report will only be good if we have better Listaflow questionnaire participation. Right now it’s not an effective form of communication within the community.

Enhance Core Contributor Onboarding

Open edX Handbook

+1 to the handbook, definitely feel free to pick up this proposal @cassie

Imho you don’t need to constrain the handbook specifically to the core contributor program, even if it would of course be used most by the core contributors. It can be potentially for all types of contributors and community members – we have talked about creating an Open edX Handbook for a while.

We can focus the content creation in the first iteration of the Open edX Handbook to the core contributor program - but this could be one (or several) chapter(s), but in the future other parts of the projects could add their own section if people find it useful?

Also something to consider: to not conflict with other medium that describe how things work, like OEPs or ADRs, it might make sense to include or reference parts or all of some of those documents in the handbook.

Last bit: it might be better to have the handbook on a github repository - this allows people to submit changes as formal pull requests, and other people to review the change before it’s enacted.

Additional proposal: Opening the core contributor onboarding courses

We have a great base for the onboarding course, but it needs to keep being iterated on. For this, the course needs to be properly open source, accessible and easy to contribute to. That would allow more people to push changes, like community members who implement a change or notice an issue, or new core contributors while they go through the course.

Currently, the course content is not publicly visible and enrollment is closed (only on invitation) and I don’t believe the source of the course is publicly accessible either. There are reasons for this (not confusing people who would come across instructions meant for core contributors, and some legal hurdles), but we lose a lot of the benefits of open source collaboration because of this, so we should approach it differently:

  • add a warning that the courses are for core contributors on all pages, and solve the legal hurdles – which in turns would allow us to:
  • make the course visible publicly
  • open up to spontaneous contributions, without having legal steps before being able to open a PR or suggest a change: publish the courses source on github and open it for merge requests (or find another way to achieve those goals).

Improve Collaboration, Communication & Reporting

Evaluate and define communication tool roles

+1 to doing this. Ideally along with this other proposal (kept separate because much more likely to be contentious:)

Ensure that Working Group names are self-explanatory

I agree that this can be simply mentioned in the handbook. For the contributors coordination working group in particular, I would put forward this proposal:

Additional proposal: Clarify the name of the working group used to discuss community-wide issues

We need to make it clearer where community members can bring up topics of governance that span over multiple working groups - like contributor programs, community issue, or any project-wide governance topic. Since what is currently called the Contributor Coordination Working Group has long served that role at the working group level, renaming it the Governance Working Group (and identical meeting name) would make this clear to people who aren’t familiar with the meeting contents. It could then help unblocking issues, or for larger topic like now, help organize summits and community-wide consultations, or liaise with the TOC as needed.

Additional proposal: Consolidate communication tools that overlap in features, keeping the open source ones

Given the strong agreement in favor of reducing the number of tools vs streamlining them (80-15%!), we should seriously look at merging some of them. It will be difficult to implement, because merging tools means removing some tools and that always brings up opposition, but we would definitely benefit from consolidating our communication tools.

Given the survey answers about preferring open source tools to proprietary ones for communication, we could consolidate tools that overlap in features, keeping the open source ones.

What I would suggest here is to move from the synchronous & proprietary tools to the async and/or open source tools:

  • Move Slack conversations to the forum (include the discourse chat module there if necessary)
  • Move the atlassian wiki to discourse too (use wiki posts & categories/tags to organize it)

This would remove 2 proprietary tools, and regroup on the forum-type discussions currently happening in 3 different places, opting for the tool which is preferred by the respondents, is async-first and open source.

Additional proposal: Improving the way we do core sprints - Open edX Handook PR?

The way we do core contributors sprints currently is not widely understood, nor very visible. We might need to integrate more of the usual tools involved in sprints: tickets, boards, sprint planning & retro. We do some of that, but once the current way we do sprints is properly explained in the

Additional proposal: Merge the Contributors Meetup Async Update and the Core Contributor Check-in

Focusing on valuable content, less often and with more of a presentation effort - do we keep the idea of a newsletter format? Imho trying to automate it further would accentuate the boring aspects - if we can do a nice newsletter with interesting content and news about the other core contributors, that would be more interesting to read? It’s more work, but getting the community to become more self-aware isn’t going to be simple. We could try it a few times as an experiment, and see what the reactions are?

Improve Fulfilling Commitments and Planning Processes

Additional proposal: Review core contributor contributions volumes for each organization & assign alumni roles

This is already in the core contributor OEP, and has recently been updated to an annual review - so this seems already in the works. But it is important to keep contributors status up to date, both for the project and the contributors themselves. It can be guilting to carry a responsibility that we are not able to fulfill. And it’s fairer for everyone when the commitments and titles match the actual work.

Additional proposal: Require Open edX partner organizations to commit maintainer and core contributor time

This comes as a sister proposal to the previous one - to ensure the core contributors have enough time dedicated by our respective organizations to maintain and improve the project, we all need to chip in a little. Maybe require a minimum number of maintainers or core contributor hours per revenue bracket, to adapt it to the size of the companies?

Improve Review Processes

Here I will be curious what @tikr and @kshitij will come up with :slight_smile:

Assignment

So far we have only assigned one proposal, the handbook which you picked up @cassie. I’d like to have at least the list of proposals above assigned, so I’ll pick up a few:

  • Opening the core contributor onboarding courses
  • Clarify the name of the working group used to discuss community-wide issues
  • Consolidate communication tools that overlap in features, keeping the open source ones
  • Require Open edX partner organizations to commit maintainer and core contributor time

Note that not everything will be accepted, so it’s fine to pick up more than you would achieve on your own - right now it’s only about getting a proposal submitted and discussed. We can take the time to work on what gets accepted afterwards, sequentially or splitting up the work among us afterwards.

Also keep in mind that I will need to be able to review the proposals before Thursday next week, as I’ll be off from Friday until the submission deadline.

2 Likes

Thanks @antoviaque - I’ll make this my focus for now :memo:

I think you have some great ideas above - let’s see if @jill @Agrendalath @kshitij @gabriel @Ali @mtyaka @pooja @farhaan @navin @gabor @braden @ChrisChV would like to pick any of them up :slight_smile: before I allocate any more to my schedule.

1 Like

Actually, I won’t be off - so that makes it a bit easier. :slight_smile:

1 Like

I’d like to take on “Evaluate and define communication tool roles” :phone:. I guess this information is something we’d add to the Handbook eventually, but it seems juicy enough to warrant its own proposal.

1 Like

I’ll be off from Friday until the deadline so I’ll try and get mine to you by Wednesday/Thursday to review and make any edits on Friday… will that work for you?

@Agrendalath @mtyaka @pooja @farhaan @navin @gabor @ChrisChV

If you would like to take part, check out this ticket and create one for yourself :slight_smile: We could really use the help!

I definitely think this is a separate investigation in itself. I like it!

1 Like

Hi :slight_smile: @jill @Agrendalath @kshitij @gabriel @mtyaka @pooja @farhaan @antoviaque @navin @gabor @braden @ChrisChV

Just a reminder to add your ideas to this post so we can all brainstorm together. @antoviaque also added some ideas here.

3 Likes

Here’s my ideas:

  1. Automated reporting of code/docs contributions.
    There’s a lot of non-code contributions we can’t automatically track, but we could do:

    • OSPRs opened/reviewed/merged
    • Forum discussions created/answered/solved
    • openedx issues raised/replied/closed
    • Working group attendance/actions taken on – this one’s harder since it’s only in Confluence, but maybe?

    We’ve had stalled efforts towards a Leaderboard for a while now (see BB-6823), but maybe now is the time to finish this?

    • Having these stats automatically generated for each contributor is could replace/prepopulate individual CC sprint updates, and inform annual reviews.
    • Having these stats across all contributors could help us measure impact of the CC program.
  2. Organization-level reporting of github contributions.

    This is a subset of my first suggestion, with slightly different motivations:

    • Measure community progress against the “elephant factor” of Axim/2U
    • Reward the big contributing organizations
    • Highlight any CCs not currently employed by one of the CC orgs who may want jobs.
8 Likes

Possible improvements that I can think of:

  • Enhance Core Contributor Onboarding: We can include the working groups that the CC should or can join in the initial nomination forum post. This can be proposed by anyone, including the nominated CC and the nominator. Then, as part of onboarding the CC, they should be invited to the selected working group meeting.
  • Improve Review Processes: We can utilize GitHub’s CODEOWNERS file to automatically notify reviewers on pull requests targeting specific sections of code within each repository. Each CC should be included in these teams as part of the onboarding process. We can already observe this in action in some repositories, such as the CODEOWNERS file in the frontend-app-authoring repository, where @openedx/2u-tnl is included as a reviewer by default due to its inclusion in the CODEOWNERS file.
2 Likes

@kshitij and I would like to submit a proposal for the Improve Review Processes category, addressing these two challenges in particular:

  • Finding reviewers
  • Review pace (or lack thereof)

We’d essentially approach this from three different angles. Here are the ideas we collected:

#1: Making it easier for PR authors (including but not limited to CCs) to manage their own PRs.

Simplifying the OSPR welcome message

As discussed recently on the Open edX forum, the repetitive value of the message is quite low. If you’re already familiar with the OSPR process the message has very little value, and some of the important information about who maintains the parent repository is buried in the message.

By collapsing individual sections of the message it should be possible to simplify it quite a bit, and key information could be highlighted better by putting it at the front of the message.

Simplifying documentation about the kinds of PRs that need product review

When following the current link for checking the list of PRs that need product review from the OSPR welcome message, it’s not immediately clear where the list is. It lives in a collapsed section on top of the target page. It would be helpful to be able to see the list right away, and for it to include a few example PRs that do and don’t require product review.

CC @cassie @Ali

#2: Making it easier for CCs to help with PR reviews.

  • Some level of automated assignment of PRs might help. A bit of bystander effect can always set in, if everyone thinks it’s someone else’s responsibility. We could have every PR automatically be assigned to the maintainer(s) of the parent repo. They could then self-request a review or, if necessary, request a review from someone else (which would help spread the responsibility to other CCs). We could at least trial this approach with a willing maintainer and see how it goes.

  • We have special views on the Contributions board that list OSPRs in need of a reviewer (all OSPRs, edx-platform only). There was a one-time announcement about these views at some point; however by now, the visibility of that announcement probably isn’t great, especially for new CCs. In order to make CCs aware that they can just go to those views, pick one or more PRs, and assign themselves as reviewers, we’d suggest that the onboarding course for CCs (and/or related onboarding documentation) be updated to include pointers about where to find PRs to pick up for review.

#3: Automating additional parts of the OSPR management process to increase the number of OSPRs that OSPR managers can process.

Making CC info for individual repos easily discoverable

In the context of BB-9084 there’s been some recent discussions on the Open edX forum and on GitHub about this topic.

One way to approach this would be to create some simple tools to get the current set of CCs for a repo, and list/order them based on a few simple factors: parent organization, number of PRs they’re currently reviewing, etc. With this info it would not only be possible to quickly identify the entire pool of potential CC reviewers for a PR, but also to determine which of them might be in the best position to pick up the review right now.

Another way would be to try and integrate CC info directly into the Contributions board (which is the main tool OSPR managers use for triage).

In line with @navin’s suggestions above, we could also consider leveraging things like the CODEOWNERS file. Since that file allows us to map parts of the code in a repository to who “owns” that bit of code, utilizing it might be especially helpful when it comes to determining who would be the best reviewer for a specific PR that has been opened against a big repo like edx-platform.

(There are tools to auto-generate these kinds of files like GitHub - open-sauced/pizza-cli: A CLI for all things OpenSauced, however, this kind of automation might not be a great idea for a project like Open edX.)

Manual OSPR management tasks to automate

Managing labels
  • Automatically set the core contributor label upon PR creation.
    • This will require getting a global list of CCs (even if someone is not a coding CC for one or more repos, they could still open a PR), maybe from the Core Contributors to the Open edX Project wiki page, and checking whether the PR author is on that list.
  • Automatically remove obsolete labels when a PR gets merged:
    • blocked by other work
    • changes requested
    • inactive
    • needs maintainer attention
    • needs more product information
    • needs rescoping
    • needs reviewer assigned
    • needs test run
    • waiting for eng review
    • waiting on author
  • Automatically remove obsolete labels when a PR gets closed:
    • needs maintainer attention
    • needs reviewer assigned
    • needs test run
    • waiting for eng review
    • waiting on author
Managing metadata for the Contributions board
  • Retrieve OSPR creation date from GitHub and use it to automatically populate the Date opened field. (Ideally, this would also be done for platform roadmap tickets.)

  • Retrieve maintainer info from catalog-info.yaml (just like we’re already doing for the OSPR welcome message) and use it to automatically populate the Repo Owner / Owning Team.

    • For repos maintained by specific individuals, include both their full name (if available) and their GitHub handle, e.g. Brian Mesick (@bmtcril).
    • As a side note, “Repo Owner / Owning Team” terminology is outdated at this point. “Maintainer(s)” or “Maintaining Team(s)” would be more appropriate (as it would better reflect current practices). We should consider renaming the field.
  • We could consider introducing a Date merged/closed field and automatically populate it with data from GitHub as well.

    • This might help us identify repositories whose time-to-merge is particularly high (though checking for the number of long-running PRs and/or looking at data from the Maintainer Pull Request Reporting dashboard could give us a sense of that as well).
Managing board statuses
  • Automatically change the status of a PR from Needs Triage to Waiting on Author on the Contributions board if the PR is marked as draft upon creation.
2 Likes

@jill Those look like good improvements - if you can revive the effort to track metrics, and make us review them regularly as a community, that will be a good contribution to the project. It would need to be anchored into the survey though - so worth including this aspect in writing down the proposal. @tikr would also be a good reviewer about this.

Same thing @navin, @tikr @kshitij - what you have suggested would work. Your proposals haven’t been written yet, right? Cf the template: https://openedx.atlassian.net/wiki/spaces/COMM/pages/4462379013/Template+Enhance+the+Core+Contributor+Experience

Btw, for the others, it would be worth picking up one of the proposals above, since we already have more than takers – in particular, check my list, I would like more of these items to be picked up. @Agrendalath @gabriel @mtyaka @pooja @farhaan @gabor @braden @ChrisChV can you chose one of those? This way the topics are already approved, and we can directly move on to the review of the proposals – which you still need to write, and there isn’t a lot of time left.

I’ll pick this one ^^ and I’ll prepare my proposal early next week. edit. Oh I just saw you picked it, @antoviaque, along with a couple more. Can I take it, or should I pick something else?

By the way, I think the main reason why not everyone is responding might be because it’s unclear whether our participation is mandatory. Can we clarify this?

I would like to pick this

@antoviaque Could you clarify which suggestions from my post that I should submit? My 1st suggestion is quite large, and could be done in pieces. The 2nd one feels more doable, but may require access to Axim’s “organization” data, which I believe is currently in Salesforce.

Let me know, and I’ll write something up when I start my week on Tuesday, so there’s time to submit before the 6 Oct deadline.

:+1: :+1:

@tikr You posted at about the same time I did yesterday, I didn’t see your post until now - it looks great! +1 on those proposals, thanks to you and @kshitij for shepherding them. :+1:

@gabriel Please feel free to pick it - sounds good! :+1: Thanks, actually.

I wouldn’t say that it’s mandatory, but it is a unique chance to establish good practices within the project, which we will all benefit from in our everyday work in the future. So I would highly encourage every core contributor in the team to to pick up one or two proposals, and try to make those proposals right. If you really have too much work, or something else that takes precedence, don’t hesitate to bring it up - but if you can fit the work, that is a worthy cause.

@ChrisChV @cassie has already picked this up - see her proposal - could you get another

FYI @Ali also has a draft proposal up on the wiki (kudos to you both!): https://openedx.atlassian.net/wiki/spaces/COMM/pages/4477485059/Evaluate+Define+Roles+of+Communication+Tools

@jill Up to you - which one would move the needle more, do you think? I would tend to think the second one, but that would require checking with them that you would get access to that data. If not, then you could carve out a subset of #1?

2 Likes