RFC-1: Request for comments (RFC) as early collaboration with our Ecosystem

General Request for Comments (RFC)
,
1

RFCs are a way for Atlassian to share what we’re working on with our valued developer community. Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

RFC (Request for Comment) is a well-known style of specification, collaboration, and change management that Atlassian proposes for communicating about proposed ecosystem features and getting feedback.

  • Author: 3 Feb 2023
  • Publish: 3 Feb 2023
  • Discuss: 10 Mar 2023
  • Resolve: 24 Mar 2023

Problem: Atlassian ships too many problems to our ecosystem

When Atlassian ships the wrong thing to the ecosystem, this creates issues for everyone. Selfishly, for Atlassian, the wrong thing requires rework which consumes valuable resources that are in short supply. Rework increases the investment needed to get to a working solution, increasing time-to-market and reducing return-on-investment. Along the way, partner- and customer-facing teams are randomized by these changes, eating up valuable resources mitigating damage and helping both internal teams and external developers rework their solutions.

Partners lack transparency into what Atlassian is working on. This leads to surprise to changes which can, at best, blow up their roadmap and, at worst, cause incidents, both in their apps and against Atlassian ecosystem components. All of which diverts resources from priority work like Cloud Migrations and from innovation as they re-prioritize the fire-du-jour. Partners have limited recourse but to publicly vent their frustration and the impact on their trust in Atlassian.

Most important is the impact on our mutual customers who experience downtime with their apps, losing trust in Atlassian and Products. This is especially true for Atlassian’s Cloud where trust and operational excellences are expected characteristics.

Proposed solution: RFC as early collaboration with our developer community

RFC (Request for Comment) is a well-known style of specification, collaboration, and change management for software and hardware developers about the protocols and interfaces between systems on the Internet. If it works for the Internet, we propose it can solve these problems in the Atlassian ecosystem.

An RFC is a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early. For the ecosystem, an RFC is a way to check our understanding of a customer problem, and to validate the indirect solutions that external developers will consume in order to solve them.

RFC workflow
RFC workflow1920×300 16.2 KB

Author

Any major technical decisions should be documented as an RFC - both to inform the broader ecosystem its being explored and to get input so that Atlassian can make better decisions faster. Even when Atlassian teams are considering a decision that seems minor, it may still merit an RFC. For example, consider making an RFC for a small- or medium-impact technical decision or a one-way door. In order to better mitigate risk, the decision should be considered through multiple perspectives to consider impact:

  • customer value
  • user experience
  • developer experience
  • distribution
  • trust

For this proposal, the technical decisions might be about any of the following:

  • Community standards. Like this RFC process, community standards can be about how Atlassian works with the developer community, or how we want the community to work within our ecosystem.
  • Marketplace and developer programs. From support offerings to partner benefits, these all need to fit together into a whole solution that helps developers build apps.
  • Ecosystem platform or product-specific technology. For example, APIs, UI modules, code libraries, CLI tools, or anything that could affect how apps are built.

Standard Structure of RFCs

  • Header. A short introduction to the RFC containing:
    • Summary: a short description of what the RFC proposes.
    • Disclaimer: standard rules of engagement
    • Flow: standard representation of status & proposed timing
  • Problem. Explain who has the problem, why it needs solving (use data & quotes if possible), what benefits would those people get from having a solution.
  • Proposed Solution. Explain the solution(s). Consider the dimensions of user experience (potential screens), developer experience (architecture, related deprecations, required frameworks), trust (especially auth & permissions), and distribution (activation, revenue model). If there were explored and rejected solutions, give insight into why.
  • Actions. Start the conversation with questions you want to answer. Explain how developers can opt-in to additional information or access.

Publish

Standardization is a constructive constraint for mutual benefit between commenters and authors. For commenters, the standard format above helps make the content easier to comprehend and to provide comments. Standard organization helps the community deal with their own variation: the right organizational tools let each commenter separate signal from noise.

For authors, standard structure makes RFCs easier to author and standard organization makes feedback easier to gather and analyze. With inconsistent formats, locations, and tagging, it becomes difficult to analyze feedback at Atlassian scale. The default should be a channel that reaches all developers. Hence, we currently recommend Developer Community and posting with the following guidelines:

  • Start a New Topic in the RFC category on Developer Community. Don’t post an RFC as a response to an existing topic or in other categories.
  • Title MUST be uniquely identified with an RFC number and the title of the RFC. For example, “RFC-2: Marketplace search terms”. During publishing look at the previous RFC and use the next number in the sequence (add one).
  • Category MUST be “RFC”
  • Optional tags MAY contain key words about the RFC. For example, “marketplace, rest-api, search”.
  • Formatting. Be aware the Developer Community (using the Discourse platform) is not as rich as Confluence; hence, keep formatting simple. Headings, bold, italics, bullets, numbering, quoting, and code are fine. Macros, tables, panels, and blocks won’t survive the translation. Images require an additional copy/paste step for each.

Discuss

An RFC is not just another kind of broadcast announcement. The “request for comments” is just the opening of a conversation with the developer community.

Who comments?

In short, everyone. We believe RFCs for ecosystem should be public and open. While it is important to get attention from those most affected by a decision, we believe the community benefits most from full transparency. Driving consensus is not just a passive effort, but an active dialog to refine everyone’s understanding of the problems we’re solving, and how those solutions will work. This is a chance to “win over” developers to a controversial solution before those developers are forced into dealing with the controversy in code.

How to write good comments?

Good comments make the overall position clear: “Agree. There are no serious flaws” or “Disagree. There are serious flaws.” Participation should follow the developer community participation guidelines. We especially call out the need to keep conversation welcoming and safe by commenting on the idea not the people (especially the author). Keep it tidy by keeping on topic and respond at the appropriate level in the thread. If you are going to comment about the RFC itself, respond to the top level. Please, keep comments constructive to help empower the community. Even serious flaws should be explained in ways that help drive better outcomes for the community.

What constitutes a serious flaw?

A serious flaw (red flag) is a problem in the RFC which would lead to not achieving the stated motivation of the RFC, meeting the ecosystem’s community standards, or the general goals of the Atlassian ecosystem. A serious flaw needs to be backed by evidence, it must be taken with deep consideration due to its ability to disrupt Atlassian, App developers, and our mutual customers.

We hope that any serious flaw in a document should be cheap and easy to fix. Without code and apps depending on that code, most flaws could be addressed by changing the spec. For ideas that are so seriously flawed that we cannot proceed, the RFC should be resolved as normal but with a statement that we’re not advancing the idea. An author should start a new RFC if the proposed solution has not been proposed before.

Who responds?

In short, the author owns the RFC. Responses to serious flaws should be timely and considered. A timely response is important to signal that the author is listening. A considered response demonstrates understanding of the commenters position, and how Atlassian will integrate that feedback.

How to write good responses?

Our Partner/Developer community will start to leave feedback, both positive and critical, in response to the RFC. They may even respond to each others feedback. Every comment is an opportunity for engagement – be curious!

  • Ask follow up questions and for clarifications (“That’s interesting, can you tell me more about….”)
  • Show gratitude when a developer shares something that helped inform your project (“That’s helpful, thanks for sharing!” and like their post)
  • Make edits to your RFC in real time and respond to close the loop (“That’s a great point! I’ve edited the RFC to reflect that. Thanks!”)

While we hope all stakeholders will follow the Rules of Engagement there will be some who test that limit. Resist the urge to defend or correct. When in doubt, a neutral statement (“I appreciate your thoughts and feedback”) is a better use of time.

Resolve

As the old bartender saying goes, “You don’t have to go home, but you can’t stay here.” RFCs must be timeboxed to avoid decision-making problems. The goal is to reach rough consensus and identify serious flaws, rather than to refine the idea to perfection: it’s not valuable until it gets built. On the last day of discussion, the author thanks the community for participation and closes the topic. Within a reasonable timeframe (we recommend 2 weeks), the author edits the original RFC topic to post a resolution as the final section of the document:

  • summarizing lessons learned
  • stating an outcome (for example, go/no-go)
  • explaining next steps (for example, “please look for our early access in 6 months.”)
  • edits the original post with a statement that the topic has been resolved and linking to the resolution post

Action

Thank you for reading this far! While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:

  • Could you triage an RFC and quickly identify whether it is relevant to you?
  • How many RFCs can you imagine engaging with in a given month?
  • Is the Atlassian Developer Community the preferred channel for RFCs to be published and discussed or is there an alternative channel?
  • Does the use of the RFC category help give greater signal to the projects being explored (or worked on) at Atlassian? Is there an alternative solution you’d prefer for that overview?
  • Does the content in the RFC Examples (below) generally include the right details or are there important missing elements we should ask teams to include?

Review Examples

To further guide this RFC towards relevant comments, we created functional examples of RFCs published today to the Developer Community. Please view these RFCs to get a better understanding and guide your comments:

32 Likes
2

Thanks, @ibuchanan . I agree with your proposal.

1 Like
3

I agree with this proposal, and I’ll add one comment:

In RFC-2, you wrote:

  • Do you agree with this proposal? If so, a like is sufficient.

I think that should be the preferred (recommended) action for general agreement without comment. That may be better than encouraging a reply with “Agree, no serious flaws.” It’ll reduce noise in the conversation and also reduce notifications for anyone monitoring the thread.

7 Likes
4

Thank you @AaronMorris1 and good point. I took an opportunity to experiment with some variation even in these first 2. I can quickly agree with your point, and I’ll roll that into our RFC guidance going forward.

1 Like
5

This should be mandatory and part of the template. There is (almost) never a single solution to a problem. Getting to know the chain of thought that led to the proposed solution is vital for community buy-in. It will also save commenters the trouble of suggesting solutions that were already considered and rejected.

However, there should also be an option to re-discuss a rejected solution. Sometimes, the reason for rejection might be related to Atlassian internal politics. Take into consideration the following reasons:

  • If we go with solution Y, we will become dependent of another team for which this is not a priority
  • If we go with solution X, it might cost more time and we do not have management buy-in for that
  • If we go with solution Z, this might be easier for developers, but it will cost Atlassian more to maintain

While either of these reasons might be valid with the context of Atlassian, it often means subpar experiences for the ecosystem. We need to be able to escalate the outcome of an RFC if the author is not susceptible to suggestions from the community just because they are beyond their control.

I would suggest to always start a new RFC once an RFC has been closed. Please also edit the RFC and prefix the title with [RESOLVED] once an RFC has been closed and make sure that it cannot be reopened.

These two quotes are both very important, because it is important to note that the limits are often tested because the community does not feel heard by Atlassian. If for Atlassian internal political reasons an RFC gets closed with a proposed solution that is still detrimental to the community, things might become heated. Obviously this should stay respectful towards the author, but IMHO not towards Atlassian and the wounds inflicted to the community as a result of Atlassian inability to deal with hyper growth.

I’d rather see authors escalate comments instead of replying with a neutral statement. In these cases “I appreciate your thoughts and feedback” will only add fuel to the fire.

I would suggesting posting a final comment instead of editing the original RFC?

Now with regard to your questions:

Could you triage an RFC and quickly identify whether it is relevant to you?
It would really help if Atlassian would be able to share an org chart of the engineering teams per product, and help us identify which parts of the products these teams are responsible for. That way, we can filter the RFC’s that originate from teams that are working on parts of the product that are relevant to us.

For instance, if we take Jira, we do not have any integrations into the “Code” feature. So any RFCs from teams that work on that feature are less relevant to us. However, we do have a lot of interest in the “Releases” and “Components” features. Being able to quickly filter on the teams responsible for the parts of the product that are interesting to us would make it really helpful to digest.

How many RFCs can you imagine engaging with in a given month?
To be honest, I think we should not limit this process based on the number of RFCs that we can digest. Because Atlassian has so many products, and so many subsets of features, being able to filter the RFCs is a lot more important than limiting the number of RFCs that can be shared with the community?

Is the Atlassian Developer Community the preferred channel for RFCs to be published and discussed or is there an alternative channel?
I’d prefer a platform that would allow inline comments and document version history (if only Atlassian has such product :grin:). In the past, CDAC has proven to be a difficult platform to track the conversation as soon as the topic became contentious. See also the discussion about granular scopes.

Does the use of the RFC category help give greater signal to the projects being explored (or worked on) at Atlassian? Is there an alternative solution you’d prefer for that overview?
I think the biggest issue is that we need to know very clearly which teams have transitioned to the RFCs in order to know what to expect. The RFC category will only work if this is done consistently. If we still feel we are missing out, it will become just another channel to track.

This means that teams that commit to this process should make RFCs part of every. single. feature. they are working on, excluding bug fixes. Not just the ones they think are going to impact the Ecosystem, because if there is one thing we have learned in the past it is that Atlassian is really not capable of estimating the impact of their work with regard to Marketplace Partners.

Does the content in the RFC Examples (below) generally include the right details or are there important missing elements we should ask teams to include?
Looks good to me!

Thank you @ibuchanan and @Anthony for your work!

5 Likes
6

I like this! At a glance everyone in the community can see likes vs comments. This aligns with the concept of ‘the ratio’ on Twitter…

(although hopefully much more positive and constructive than the ‘discussion’ on that platform!)

1 Like
7

Agree - this sounds like a good idea. But how will the Atlassian team know when to raise an RFC?

Saying this is easy, doing it well is hard and the RFC process itself isn’t the issue (and sounds like a good mechanism).

1 Like
8

@james.dellow,

how will the Atlassian team know when to raise an RFC?

That’s a very insightful question. And I agree that “doing it well is hard”, but our hypothesis is that a standard “RFC process” can make it easier. While researching this, we identified RFCs are well-known on the Internet and inside Atlassian. Even without calling them RFCs there are teams who have good habits about early collaboration with developers & partners. In this first stage, we are trying to prove we can make things easier for those already motivated teams by helping do each of the “stages” faster: author, publish, discuss (respond to comments), and resolve. By removing many decisions that don’t really add value (like essential structure, where to publish, whether to respond, and whether to resolve), we think it will reduce the cognitive load.

Behind this RFC, we’re also building out some analytics so that we have the kind of data that convinces more Atlassians the process is worth following. So after some number of RFCs from the parts of Atlassian that already engage the community, we’ll take on spreading the practice into the parts that don’t. So far, I have seen a good deal of evidence that more teams would engage, if only they had some guidance. Unfortunately, Atlassian is large enough now that I could not provide that kind of guidance directly, at the rate of demand. Hence, declaring standards like this RFC process itself is a “self-service” mechanism to help spread the practice.

I realize that “working the process” is still short of a solution to “doing it well”. My thought here is the mantra I’ve often heard from the agile community, “If it hurts, do it more often.” The implication being that practice will solve the “doing it well” problem. That said, I would be happy to take input. What advice would you provide to Atlassians about publishing their first RFC?

2 Likes
9

Would Atlassian (@ibuchanan) go as far as limiting changes to ecosystem technology to resolved and accepted RFCs only?

2 Likes
10

@UlrichKuhnhardtIzym1,

Short answer: not quite that far.

While I appreciate the sentiment, I think you’re putting a lot of trust into a process that has only just begun. If we tried to go that far right now, I think it would just bounce us from one poor extreme (too much uncontrolled change) to the other (too much “big batch” change).

In the near term, we need to focus on making the RFC practice “work” both in terms of getting the “cost to author” lower and the “value of participation” higher. On the side of authoring, we’re already learning from the first 4 RFCs about the kinds of written guidance we can provide. On the participation side, we’re looking at “wiring this up” to some of our existing data collection tools to make sure this continues to work at scale.

In the longer term, I think we could consider a model of “RFC required”. But I think we’re going to need more surrounding standards & practices. For example, I think we need a better “lifecycle model” around the products & technologies in the Atlassian ecosystem. Some components might need to evolve very quickly in a mode of “pioneers”, with only a small set of highly-engaged partners, and without the formality of public RFCs. While other components have found their market-fit and need to evolve carefully with a large set of self-service partners where the model is more “town planning”. We could consider “RFC required” for this subset. In other words, I think we need to better account for the variation in Atlassian and the developer community before we would resort to “one size fits all” requirement of RFCs.

All that said, I am certainly hoping for a bit of “community enforcement” even now. It is perfectly reasonable for anyone to ask Atlassians, “Why didn’t you engage us sooner with an RFC on X?” Indeed, I hope you will.

3 Likes
11

Flip side of @UlrichKuhnhardtIzym1 question - how can we make sure that Atlassian doesn’t abuse these RFCs? I’m slightly concerned that we end up getting 500 RFC’s a day and things get implemented by Atlassians going “Nobody spoke up and they had their chance”. Ie. Can we please make sure that the RFCs are not the only way that Atlassians seek out input.

Thanks,

/Daniel

12

@danielwester,

Can we please make sure that the RFCs are not the only way that Atlassians seek out input.

I realize Atlassian has done that kind of thing with EAPs in past. While I’m in complete agreement on the “not the only way”, I’m not sure what to do about “please make sure”. It feels like the perpetual dilemma of “can you make sure you do enough testing”. I think (or hope) we all know, “you can’t test quality into a product, you have to build quality in.”

I think that’s a bit the same here. With Developer Experience (including me) acting as your advocates, we can keep an eye out for that disingenuous application of RFCs. But we are a small team and I don’t think we can “prove the negative” anymore than a QA team can. Generally, there is always the problem that asking us to check ourselves is asking the fox to guard the henhouse.

What we’re trying to do here is “make it easier to do the right thing than the wrong thing”. To that end, we are working on other complementary practices to RFCs that should cover cases where RFCs won’t work, provide more (and predictable) points of interaction, and do more to “build quality in” (rather than focus on checking for it).

1 Like
13

Hi @ibuchanan -

Watching this new process unfold, I think I’ve noticed a minor technical flaw:

I’m finding that monitoring RFC’s for edits is very challenging. It seems that the forum 1) doesn’t highlight a post as unread when it is edited, and so I think you need to click through RFCs and look for the little edit icon . And 2) it doesn’t make identifying the edits easy (i.e. viewing redlines).

For example, I’ve already reviewed and commented on RFC-2, and I can see that you made edits 6 days ago. But is there a way for me to know what your edits were? (Did you address any comments or were you just fixing typos?) The tool doesn’t make it clear.

Again, just a technical problem, with possibly some procedural solutions. Or maybe just user error (mine)? :slight_smile: I definitely agree with the proposal of keeping RFCs updated.

Thanks! I really appreciate that you’re giving this new process a shot.

2 Likes
14

@AaronMorris1,

Keeping track of edits is an important point and one we decided set aside for the sake of getting something out the door quickly. I assure you that it’s not something you’ve missed; Discourse just isn’t made for the kind of “change tracking” that would best fit. Fortunately, we have not had an RFC undergo “major revision” or everyone would notice. We’re considering switching over to Confluence but that will create “yet another channel”. For now, we’ll try to do better with some manual notes about edits.

2 Likes
15

Another option would be to either create a comment with the adjusted RFC, or close the RFC and start a new thread. Would that be an option?

16

@remie

Possibly.

For very small edits, like the one I remember making on RFC-3, it was just tagging and a little formatting where I’m not sure a repost would make sense. I don’t remember changing RFC-2 in response to @AaronMorris1; maybe I clicked edit on the wrong post and didn’t “cancel”? In any case, the tool’s memory of “an edit” is confusing and could still lead to people wondering about the change.

I’m leaning toward this, option as the right way to handle a serious redraft, as we will need for RFC-1 to account for all that we’re learning with these first RFCs.

I’m still drafting some observations & learnings (including on prioritization; I haven’t forgotten). From the authoring perspective, what’s feeling “right” is to pull out a section for reposting & subsequent comment, which fits somewhere between your 2 proposals.

And, one of the considerations I’m trying to hold in mind is the importance of resolution. Without experience on trying to draft one and tie-up all the loose threads & thoughts, I’m not sure how any of these style of revisions would fit.

Overall, I’m inclined to try both of these suggestions. I think RFC-1 would benefit from “close and redraft”, likely after the end of the discussion date, therefore creating a new timeline. And RFC-2 from “edit as a post”, the scope of changes is shorter.

1 Like
17

Oh gosh. Please don’t start a new thread. We’ll be overloaded by Atlassians creating new threads as soon as they’ve tweaked an idea slightly. We’ll end up having to have versions of the threads. There will be multiple versions of conversations going on. It will be what I expect from Atlassians abuse of a forum.

Can we please use something that is meant to do proper versioning of documents and commenting? If not Confluence - Google docs?

2 Likes
18

Discourse supports edit history just fine (including a neat diff), I think it has simply been deliberately disabled (or limited to staff) on this site?

I always wondered what the rationale behind hiding the edit history is, so provided there isn’t an important one, you could enable it again and just add a comment for any significant edit so that watchers are notified and can check into the diff.

5 Likes
19

@danielwester,

No, not new thread for slight tweaks. I’m not committing to new tooling but it’s on our backlog. There are more “moving parts” here than are apparent so I appreciate your patience so far.

@sopel,

Discourse support for diffs is news to me! I’ll look into it.

1 Like
20

This morning, I closed the first “real” RFCs:

While we wait for resolutions on those specific topics, I wanted to reflect a bit on what we learned from the first discussions. Overall, RFCs seem to be going well. Internally, we have additional topics lined up, and we’re creating more guidance as we learn, so each new one will be better and better tuned to a useful collaboration with the developer community. Externally, we had high participation that has lead to genuine learning and improvement.

Constructive input

So far, we have observed some commenting patterns that really pleased us. We saw a lot of examples of constructive comments. The following reflects some of the engagement patterns that were really helpful.

  • Asking for more clarification in areas where commenters need to understand more. We might not have the details now, or be ready to provide them while the RFC is open, but your questions will help us to write better RFCs over time and to know what we need to answer before we finish a project.
  • Suggesting what would make a problem worth solving.
  • Suggesting better solutions, or enhancing with your ideas about how to create more value.

Votes and vetoes

We saw some engagement that framed RFCs as the means to “veto” an idea. Clearly, that reflects the guidance I provided in “How to write good comments?” However, RFCs need to reflect “a bias for action”: here’s a problem; what can we do together to find a solution? While we’re utilizing some democratic methods to explore those topics, the ultimate decision lies with the author, not a vote from the community. To clarify our intent, RFC is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Prioritization

In recent discussion, I asserted that “priorities are out of scope”. While the RFC problem statement should convey value (and hence a sense of priority), meaningful discussion of priorities (plural) demands a discussion of relative trade-offs. For the RFCs, we’re not ready to have that conversation when we haven’t yet made enough work visible to discuss sequencing. Even when we achieve greater transparency as more projects get an RFC, there are still trade-offs that remain internal to Atlassian. Therefore, we assert that RFCs should be treated as independent of each other and that relative prioritization is “out of scope” in the RFC threads. Please keep the RFC comments to negotiating toward the most valuable thing to build.

We can have relative prioritization discussions based on other sources, in other categories. For example, it is valid to bring up the prioritization of our Cloud Roadmap or Forge Roadmap. In time, we hope the RFC process is so widely adopted that every RFC lands on a roadmap, and that we can have a discussion of priorities about the roadmap.

Proposed revision: How to write good comments?

Good comments focus on identifying serious flaws and providing constructive feedback. Participation should follow the developer community participation guidelines . We especially call out the need to keep conversation welcoming and safe by commenting on the idea not the people (especially the author). Keep it tidy by keeping on topic and respond at the appropriate level in the thread. If you are going to comment about the RFC itself, respond to the top level. Please, keep comments constructive to help empower the community. Even serious flaws should be explained in ways that help drive better outcomes for the community.

While the RFC problem statement should convey value (and hence a sense of priority), meaningful discussion of priorities (plural) demands a discussion of relative trade-offs. RFCs should be treated as independent of each other and that relative prioritization is “out of scope” in the RFC threads. Please keep the RFC comments to negotiating toward the most valuable thing to build.

  • Ask for more clarification in areas you need to understand better. We might not have the details now, or be ready to provide them while the RFC is open, but your questions will help us to write better RFCs over time and to know what we need to answer before we finish a project.
  • Suggest what would make a problem worth solving.
  • Suggest better solutions, or enhancing with your ideas about how to create more value.
7 Likes