Improving communication via the CUE open source project

[myitcv]

Introduction

When folks interact with the CUE open source project we often hear feedback like:

• What is the project roadmap? What is the CUE project focussed on?
• In what release can I expect to see feature X? Is it even planned?
• When will bug Y be fixed?
• When can we expect to see performance improvements in CUE?
• What is the plan for the upcoming releases?
• What is the plan for modules? What's next?
• There are lots of open issues - are things getting out of control?

Communication is a key part of running any project, especially an open source project.

This discussion includes a proposal on how we plan to do things a bit differently, to try and improve our transparency going forward.

In parallel to engaging in this discussion, we will start a trial that implements the proposal, and learn as much as we can through that trial.

Feedback on the proposal and the changes you see when we start implementing the trial would be greatly appreciated.

Proposed structure

The CUE project uses GitHub as one of its main communication channels, in addition to Slack and various social media channels. The issue tracker at https://github.com/cue-lang/cue is the main entry point. We do not propose to change that, rather we plan to get more from the issue tracker by making better use of things like projects, labels etc.

• The main issue tracker will remain at https://github.com/cue-lang/cue/issues
• Introduce two kinds of Projects. Projects are a new way to manage and view issues.
  • Release Projects - for planning upcoming releases
    • e.g. v0.8 release
    • The "status" field is repurposed to each semver release, e.g. v0.8.0-alpha.1, v0.8.0-rc.1, v0.8.0, v0.8.1
  • Roadmap Projects - roadmaps for parts of the CUE project
    • e.g. Evaluator, Modules, cuepls (LSP), cuelang.org, adapters…
    • "status" field retains the GitHub default: backlog, in progress, planned etc
    • Iteration field optionally allows for grouping according to sub-projects/sprints/etc
    • Start and end dates (within iterations) allow for indication of sequencing of issues where are dependencies
• Issues
  • Issues are assigned to Release Projects when there is a clear plan to fix a bug or deliver a feature as part of a release
  • Issues can also be assigned to Roadmap Projects to indicate whether or not the work is planned as part of a roadmap
• Milestones
  • We will not use milestones going forward: they are replaced by Release and Roadmap Projects
  • They are rather coarse and limited compared to Release Projects; for example, they are limited to a single repository
• Labels
  • Labels are used to categorise issues, e.g. marking an issue as a bug
  • An issue belonging to a Roadmap Project is in effect a label. e.g. an issue belong to the modules roadmap indicates it's related to CUE's modules
• Discussions
  • Like issues, labels are used to categorise discussions.
  • Discussions cannot be part of projects, at least not yet
  • We will continue to respond to questions etc in discussion along with the great interactions we are having on Slack and in other venues
• Pull requests
  • Most changes to CUE are made via GerritHub but we will continue to fully support changes via PRs

The thinking behind switching to Projects is largely driven by:

• The existence of a Roadmap Project is a signal itself of an area of focus within the CUE open source project
• Roadmap Projects serve as a natural means of communicating the status and phasing of key parts of the project
• Projects are automatically kept up-to-date as issues are updated; meaning we have a single source of truth shared with our community
• Release Projects will provide a more structured and finer grained view than milestones

Next steps

• Engage with feedback, questions etc in this discussion
• As a trial, implement the proposal for the v0.8 release and the Evaluator, Modules and CUE LSP roadmaps
• Use the new Roadmap Projects as the basis for our community call updates
• Post updates in this discussion, adding to the FAQ below

FAQs

Where are we with the new evaluator? Why did v0.7.0 not include performance improvements?
Per a recent thread on Slack discussing CUE performance, our communication on performance improvements has not been great. For that we would like to apologize. Our lack of communication in no way reflects our prioritization: performance and error messages are both critical to CUE's success. We are working on a more substantive response and set of "next steps" which will be shared in a later discussion.

But to summarize for now: the new evaluator is in full development. Many of the existing tests are already passing. The main blocker for releasing an experimental version is the implementation of disjunctions, which is currently in full swing.

What will the release cadence look like going forward?
Our current focus on modules and cuepls (in particular) is going to require that we ship more releases in order to allow people to try out new features and bug fixes. So you can expect to see a much higher cadence of releases at least in the short-medium term. Because we need to keep things fluid, especially pre v1, there are no current plans to move to a more structured approach like Go.

When do you assign an issue to someone?
When they are actively, or about to start, working on it.

Does an issue have to belong to a project?
No. An issue that does not belong to a Release Project means the bug fix or feature is simply not planned to be part of a specific release. An issue that is not part of a Roadmap Project means that there is not, for now, a well-named part/aspect of the project that we have captured as a Roadmap Project. The list of Roadmap Projects is neither final, nor complete. Especially in the early days, things will be quite fluid until we find the right balance/names/groupings etc.

[myitcv]

An excellent bit of feedback on Slack pointed at https://github.com/users/nesk/projects/1/views/1 being an example of where a GitHub Project-based roadmap is done well. If folks have other examples of where things are done well, please do share them!

[myitcv]

A point raised by @mxey on Slack:

One thing I have noticed is that since you use Gerrithub and not GitHub PRs, it's hard to see what changes are “in flight”. I know there is a link to the Gerrithub page of CUE somewhere, but it's not trivial to find, compared to the Pull Requests header

Capturing that comment here so that we don't lose it.

[PerArneng]

It's much easier to follow an OSS project when changes are linked to the issues like they are in GitHub so that you can follow a complete timeline of what has changed in an issue and all the discussions around it. Some people love Gerrit but I think the strength you get from having the traceability of going full on GitHub is worth the change.

[mvdan]

We aren't considering switching away from Gerrit at this point - we would lose the ability to properly "stack" dozens of commits to be reviewed separately, and reviewing large changes on Gerrit is also a lot easier to do. Simply put, the large feature work like evaluator performance and modules could not have made as much progress up to this point if we were using GitHub PRs :)

That said, we can certainly do better in terms of surfacing what changes are in flight. Two ideas:

• When a Gerrit change is created that references an issue, we should have a bot posting a comment on the issue with a link, much like Go has done for years. This should be helpful to notify those watching the issue, and to answer the question "does this issue have an in-flight patch?".
• Include a promiment link, perhaps via a badge at the top of the README, to see the current pipeline of changes being reviewed and soon to be merged. Personally I use https://review.gerrithub.io/q/projects:cue-+is:open for this, as it is a view of all open changes across all CUE repos, latest first.

[rawkode]

https://graphite.dev

Keeping work on GitHub would do wonders to increasing transparency and encouraging external contributions.

[mvdan]

@rawkode to be clear, we already accept pull request contributions, and review them there - as long as the changes are reasonably small. For example, see #2764 or #2729 as two recent ones.

Fully agree on increasing transparency - any feedback on my two ideas above, or any further ideas, are welcome.

[marxarelli]

Gerrit's change model was before its time and as someone who has been part of an unfortunate migration from Gerrit to GitLab, I say beware of all the powerful features and operational performance you would be losing by doing something like that. (Sounds like you're not though.)

I say use whatever makes sense for your contributor base, workflows, and values. And yes, surfacing progress on features and milestones in some higher level form would be helpful. Personally I have never found GitHub PRs interface to be useful for tracking any of that.