TSC: Improving Community Experience (May 2021)

[hcgatewood]

Improving Community Experience

Magma community experience was unpleasant and under-productive. We've been working to improve it.

Context

At the formation of the TSC, we identified two key areas where the community was experiencing pain points

• 🚨 Onboarding community members, both to the community and to the dev process
• 🚨 Communicating developer expectations

To that end, we identified and landed updates to the community experience along 3 axes

• 💧 Streamline dev process
• 📝 Document dev process + expectations
• 🎙 Publicize project resources

💧 Streamline dev process

Pain points

Getting a PR merged requires two things: maintainer approvals and passing CI checks. Garnering sufficient approvals and passing required CI checks was a non-trivial task which authors were often unable to navigate.

• PR authors didn't know:
  • Required maintainer approvals
  • Who to message when blocked (review or failing CI)
• Maintainers didn't know:
  • Which PRs needed their attention
  • Which maintainer should review a PR
  • When a PR was ready to be merged
• Manual review required to upkeep PR health

Resolutions

Review process

• ✅ Team-based GitHub codeowners (approvers-* teams)
  • Authors understand required maintainer approvals
  • Maintainers know which maintainer should review a PR
  • Related: Clarified project permissions (and Permissions changelist), Clarified project teams
• ✅ Toast Slack integration
  • Maintainers are automatically messaged when action required
• ✅ ready2merge label
  • Maintainers know when a PR is ready to be merged
• ✅ CI checks documentation
  • Authors know who to message when blocked on failing CI

PR health

• ✅ Automate linting and static analysis
  • cloud_lint style and static analysis for Orc8r
  • reviewdog-managed linters for: GCC warnings, Python, shell, Dockerfiles, YAML, and common misspellings
  • CodeQL static analysis for: Go, Python, JavaScript
• ✅ Codecov for full-project code coverage metrics
  • Track code coverage over time, identify under-covered parts of codebase
  • Inline code coverage directly in pull requests (via Sourcegraph and its Codecov extension)

CI health

• ✅ Pull critical tests into merge-blocking CI checks
  • session_manager_test unit test session_manager
  • mme_test unit test sctpd and mme
  • cwag-build build CWAG containers
  • feg-build added a check for container crashloop
• ✅ Process for freezing or reverting breaking PRs
  • “CI oncall” to manually manage post-merge CI checks, to determine whether master is healthy
  • Guidance for CI oncall for reverting breaking PRs
  • Guidance for CI oncall for freezing master branch when master is unhealthy

📝 Document dev process + expectations

Pain points

Contributing to the Magma project is a non-trivial endeavor — it's a project with multiple languages, platforms, and applications, and requires hardware in the validation path.

Community contributors struggled to understand baseline development workflow and expectations around contributions.

Resolutions

General

• ✅ Reorganize Docusaurus sidebar with community focus, aligned to "what do I want to do"

Onboarding

• ✅ Developer Onboarding onboards developers completely new to Magma

Contributing

• ✅ Development Workflow covers required PR practices, including an opinionated description of best-practices
• ✅ Contributing Conventions covers conventions and expectations for code contributions — for the project as a whole, documentation, specific languages (Go, Python, and C++ forthcoming), specific tools (gRPC, Swagger, YAML), and more
• ✅ Continuous Integration Checks annotates CI checks with purpose and points of contact

Maintaining

• ✅ Codeowners Workflow provides guidance to codeowners on shepherding community contributions and when force-merging PRs is acceptable
• ✅ Proposals Process provides guidance on proposing new features, getting feedback from the community, and aligning on a final design

🎙 Publicize project resources

Pain points

While community-facing documentation now exists, it's still siloed in the Magma Docusaurus — which has 130 readme files at the time of this writing.

New community members don't know to sift through the documentation. Instead, we can bring the documentation to them at key touch points.

Resolutions

• ✅ Community calendar for inviting entire community to public meetings
• ✅ Revamp project README with community entry points, contributing resources, and a modernized hero banner

• ✅ GreetBot Slack integration to welcome new Slack members with community resources

• ✅ PR bot to comment on opened pull requests, welcoming authors with how to get PR merged and follow community standards

Conclusion

We're still looking to do more. Please follow up in comments on this post with your feedback, and ways we can improve the process of onboarding community members and communicating developer expectations.

Huge #thanks to @themarwhal and @electronjoe for their fantastic work in driving this effort forward. And big #thanks to @PARitter and Gale for advising and supporting the improvements!

And #thanksteam for pulling together to support the Magma community 💯🌟

[themarwhal]

Thanks @hcgatewood for being a fantastic TSC chair and for this great summary. 🙏
Excited to get more things done!

[shawaj]

the slack community invite does not work unless you have an email address from one of the following domains:

• openstack.org
• freedomfi.com
• openairinterface.org
• wavelabs.ai
• altencalsoftlabs.com

The documentation implies this is an open community - is this an oversight or is it intentional?

[amarpad]

Must be an oversight. cc @galemccommons, not sure who has the keys to the slack account.

[wendallkaters]

Thank you for pointing out this out! Not sure why the settings changed. Updating the redirect link. Correct link should be associated with slack.magmacore.org now.

[ulaskozat]

It still does not work, I think.

[PARitter]

The invite link "https://slack.magmacore.org" as shared by @wendallkaters has been tested and confirmed to work. The original link referenced above "https://magmacore.slack.com/signup#/domain-signup" does appear to still be broken.

The website is being updated to use the link provided by Kendall. We should update the rest of our collateral to use it too.