How to track and communicate on specific development topics in our work?

[aj-stein-nist]

Question

This has come up a few times in the last week, and it came up in particular from a particular attendee in the 6 October 2022 OSCAL Lunch with the Devs meeting. So it seems prudent to address it in a more direct intentional way with proposals now.

In a previous retrospective and internal status meetings, we have similarly acknowledged whether or not we use "epics" in GitHub (this can mean a few things: a specific label, by milestone, creating a tracker issue and putting [EPIC] ... in the beginning of the issue title) anymore or consistently. Sometimes, a "development topic" in this case could be something smaller, average, or larger than a such an "epic" in the ways we describe them in GitHub. A topic could even be a theme that supersets over a bunch of epics, or it might not. Today, it was asked for how the different parts of the progressing rules work in "epic-level" issues #1058 and #1059, and their various sub-issues are being tracked and handled. Smaller or bigger than that, for different work streams it is not clear.

We have a few options for technical and social methods for this, with the goal of making this info transparent and communicable inside the team (NIST staff) and to the larger outside community. How do we communicate that? How do we as a team unify around a single approach? A couple of ideas have been posited in the last week.

• One recommendation from @Compton-NIST from A.J. misunderstanding Chris and incidentally posing his own idea: making a milestone not like (past) tracking of sprints, but for themes like "Mapping Enhancements" or "Rules"
• @Compton-NIST's actual recommendation was to use a project (classic or beta board, note a milestone)
• Another recommendation from @wendellpiez is being more intentional and consistent with issue tags, and additionally @JustKuzya cited making sure this can be used/cross-referenced with the new board that uses beta Project style tracking

I am sure there are other ideas. I think we should have some discussion here, with NIST staff and community, and then I will consider drafting a decision record for NIST OSCAL leadership's staff to make with the team and move forward with a unified approach.

Thoughts?

[Compton-US]

Thanks for summarizing this! I was thinking more along the lines of a Project board than a milestone, but that's not to say that milestone couldn't be the best thing. My only con on the labels is that too many labels makes them less valuable for the "action required" aspect that we used them for now.

[aj-stein-nist]

Thanks for summarizing this! I was thinking more along the lines of a Project board than a milestone, but that's not to say that milestone couldn't be the best thing. My only con on the labels is that too many labels makes them less valuable for the "action required" aspect that we used them for now.

Not a bad idea either I can add that as a separate item on the list.

Would you be interested in drafting a straw-man decision record for discussion not this week, but the following one? We have time, but I didn't just want it to be me writing by myself, and want time to collect feedback from others. :-)

[wendellpiez]

Looking at the labels one sees an entire little history of attempts to wrangle Issues into order, including LoE labels (not being used anymore) and Scope labels (which I actually use).

I agree that currently we are not using the "epic" concept effectively or even consistently. Probably because Github has no real analogy to a Jira (or other) 'epic' so it effectively just a meta- or tracking ticket.

Maybe we need to (a) clean up / declutter the Labels, and then (b) discuss and determine what kinds of Labels we will try to use going forward. This won't solve the problem but it would feel good, it can't hurt, and might help.

[iMichaela]

@aj-stein-nist @Compton-NIST and @wendellpiez - How do we want to allow the community or other team members provide feedback in an easy way (not just leave comment)? Should we keep each option clearly stated as a 'comment' on top of the issue so we and community members use the default like feature as a clear (binary) voting mechanism and provide comment only when they have additional feedback? We can also send an email to our mailing list (with explanation) asking to vote... Thoughts?

[aj-stein-nist]

How do we want to allow the community or other team members provide feedback in an easy way (not just leave comment)?

Well I guess this on me to answer since I opened an issue (not a discussion post).

I specifically opened an issue for our consideration and not to start with directed community feedback and voting (as opposed to the other one) on the initial ideas. I thought we would only loop in the community more directly after we thought about approaches and fleshed them out. This is about how the NIST team decides our work. I just opened the issue to discuss and keep the community aware. I had hinted that my tentative plan on this was:

I will consider drafting a decision record for NIST OSCAL leadership's staff to make with the team and move forward with a unified approach.

It was only my suggestion (but not very well-formed yet) that we ought to write about the options and then discuss with the community and internally once we had a better, more complete proposal and rationale, not just vote up or down on the comments.

That said, the decision record was meant to come later (if we all agree to it, including Dave when he's back). Do we want to convert this into a discussion?

[aj-stein-nist]

@david-waltermire-nist agreed that a more deliberate internal discussion of merits and consultation with the larger community to find an approach that works for "us" (the NIST OSCAL staff) and the larger community during today's weekly status meeting.

• We to find out what problem we are solving for, not immediately drives for solutions (the "what" and not the "how")
• We want to scope a future conversation about what we can do that is productive for the team and solves the goal ("the what") and working this UX/CX work with the community does not take cycles/bandwidth from other higher priority research/dev/eng tasks.
• We want to bring this up during our next OSCAL Lunch with the Devs meeting. AJ volunteered to steer conversation for that, and solicited other NIST OSCAL team members who were/are interested to join him
• A.J. agreed to write up a decision record during and after internal team and community engagement and not to engineer a solution during weekly status meetings. We will explore options, brief Dave and the team on a recommendation, and we will agree to that after the decision record is drafted and reviewed

Thanks to @canb227, since he started all of this and I look forward to looping him and other community members into as we see fit. :-)

[aj-stein-nist]

Moving to Sprint 61.

[aj-stein-nist]

Focus should be on development themes in the future, near-term or long-term, not for the team to retroactively apply to past or recently worked themes and cause a lot of busy work, per Chris in sprint planning.

[iMichaela]

Proposed plan of action for the team members to consider and provide feedback:

1. Declutter the pool of labels currently used.
   • important labels to have:
     - priority labels,
     - effort level,
     - bug,
     - question,
     - developer experience required (DER): (e.g DER:METASCHEMA | XML | JSON |
     - discussion needed - internal (DNI)
     - discussion needed - external (DNE)
     - ? what am I missing ?
2. Document how to consistently use the labels kept
3. Use a project board for each major topics. A list I can think of today:
   • Rules,
   • Checks,
   • Controls mapping model,
   • CRM mapping model,
   • Inherited controls and Leveraged authorizations,
   • Requests for collaboration
   • Bugs breaking backwards compatibility
   • ? what am I missing ?
4. For each major topic, EPIC issues can be used to group related issues. More than one EPIC is possible for each major topic.
5. The (decluttered) labels can be used for issues associated with the EPICs.

I will send a meeting invitation to discuss the above draft decision record . A diagram can be added, If needed. Some definitions must be also included.

[aj-stein-nist]

Michaela I like what you have drafted thus far, but I also think there are some things we have to think about to "tell the story" about topics of work, and that is where I am fundamentally concerned beyond labeling collections of issues (topic->one or more epics) around: what is the current outcome, and what are the epics associated with it, what is the current status? I hope we can discuss that in the meeting.

[iMichaela]

I also think there are some things we have to think about to "tell the story" about topics of work, and that is where I am fundamentally concerned

@aj-stein-nist - valid concern. If I understand it correctly, you think we need a"'live" summary/abstract for each topic. Should it be something like a TOC.md with hyperlinks of all EPICs and related issues and the status pulled from the issue? *This takes extra work to manually generate and constantly maintain the TOC.md up to date if no auto generation is possible. And where would you keep those TOC.md files? In the OSCAL GitHub repo and generate a OSCAL status dashboard page on OSCAL pages that will list all Project boards, and automatically populate the summary with the TOC.md? From there, even a non-developer can navigate to learn more and offer to collaborate with a click of a button that would mailto:oscal@nistgov (invoke the mail client app) and include the selected topic in the subject line.

We can talk next week during the meeting.

[wendellpiez]

I for one am finding the "Profile Resolution" label to be useful, even essential so I am not sure that one should be pruned away. Maybe an alternative is being proposed for that level of findability.

I am also not sure that documenting how to use a labeling system actually ensures understanding and conformance. Indeed there is more than one way to use them. I'm afraid that this makes me less than helpful except perhaps as a sounding board or devil's advocate.

Would it be possible not to stress this question until we have actually moved a few Issues onto and then off from the board? By showing what works we can then see what is no longer working / getting in the way. Apologies if this comes across as a wet blanket on a worthy initiative. I think I'm in favor of the goal just not sure how to get there most easily.

I for one would like new guidance specifically to learn about spikes, work item 'owners' vs other participants, all that stuff that I am expected to know. What makes an Issue closable or not etc. I am sure @aj-stein-nist is already thinking about this. But this wouldn't be so much how I must use the labeling system as how I can use the labeling system -- and observe it being used by others.

[iMichaela]

Would it be possible not to stress this question until we have actually moved a few Issues onto and then off from the board? By showing what works we can then see what is no longer working / getting in the way. Apologies if this comes across as a wet blanket on a worthy initiative. I think I'm in favor of the goal just not sure how to get there most easily.

Sure. A strategic plan needs an implementation plan :) which should include testing.

[aj-stein-nist]

We can talk next week during the meeting.

We can talk about it next week when the meeting is set up, I would rather constructively discuss it than write destructively on the topic.

Would it be possible not to stress this question until we have actually moved a few Issues onto and then off from the board? By showing what works we can then see what is no longer working / getting in the way. Apologies if this comes across as a wet blanket on a worthy initiative. I think I'm in favor of the goal just not sure how to get there most easily.

I think this a wonderful theme we need to focus on as a group. I did not put this comment or the prior one to insist we hash it out in the comments, just adding important points about my perspective and things I will likely discuss as I review my comments and notes on the issue at that time.

Have a good weekend, y'all.

[iMichaela]

@aj-stein-nist and team - the meeting was scheduled on Feb 7th, at 12:30, as virtual office hour.

[iMichaela]

02/09/2023 Update:

I met with the team on Feb 7th, and the feedback and the discussion was captured here

[aj-stein-nist]

Thanks for helping with this. Let us know how we can help.

1. Will you need assistance with the ADR drafts?
2. Are we doing another office hours last week as discussed?
3. Would you prefer I spike the part with work stream management this sprint (in the next 3 weeks)? I can do it quickly and track it under this work if you'd like.

[aj-stein-nist]

2. Are we doing another office hours last week as discussed?

Re my question about 2, disregard, you clearly made an invite in advance I had not accepted on my calendar. Silly me!

[aj-stein-nist]

So we discussed this in today's status meeting, we are ready to move forward on the labelling, more to do on the epics part of this per the summary documents.

@iMichaela, are you intending to make an ADR for the labels, or will you need assistance doing that? Can I or others in the team assist with it? I leave it up to you.

I had asked before and presume I might have to contribute, do you want to continue with the other epic-related piece of this, shall I present to the team a recommended approach as part of that or separate of that? Let me know and we can sync up next week.

[iMichaela]

• The following ADR for GH Labels will be submitted as a PR if no other comments are received prior to Feb 21, 2023, EOB.
• For additional actions related to this issue, a.k.a Draft ADR How to Handle EPICs and Related Issues, additional internal meetings are necessary.
• Minutes of the How to track and communicate on specific development topics in our work? #1496 are available [here](Overall notes: https://hackmd.io/YS5ib1yMQ4ab-7Ocyy2vUA)
• ADR for GH Labels draft with comments is captured here

# Use of Labels in OSCAL Project(s)

Date: 02/17/2023

## Status

Feedback Requested

## Context

We wish to improve communication within the team and among the community members. Labels we use in OSCAL repositories can be a part of the effort.  We have discussed a number of options around labels and we will use an ADR to capture and document our approach moving forward.

- Related to Issue [#1496](https://github.com/usnistgov/OSCAL/issues/1496)

## Decision

Existing labels were reviewed, a subset of labels is kept and new ones are defined.

The lists of labels that follow will use across OSCAL repositories.

#### General labels:

- breaking change
- community feedback needed
- developer experience
- discussion needed
- epic
- rfc
- scope: ci/cd
- scope: content
- scope: documentation
- scope: metaschema
- scope: modeling
- scope: tooling and APIs
- scope: website

#### Project-specific labels:

- model engineering
- research
- profile resolution

#### Default (GH) labels:

- bug
- duplicate
- enhancement
- help wanted
- invalid
- question
- wontfix

#### Technology-identifying labels: Used by the ```dependabot```

- dependencies
- docker
- github_actions
- java
- javascript
- go
- python
- ruby
- submodules


#### Labels to be sunset/removed

- Lunch with the Devs
- Model Review 

### Use of Labels on Issues

**Creation of Issues:**

1. When issues are created, labels will be assigned by the author.
2. When the issue is triaged, selected labels will be reviewed and adjusted as necessary, including the addition of any omitted labels.

**Consistency Across Projects**
Except for the _Project-specific labels_ all other labels shall be used per their description


## Consequences

- Too many labels, or labels that are inconsistently used, will cause confusion.
- Detail information capturing the spike that researched this ADR is available [here](https://hackmd.io/UrSjUKGiQRuiA2VJLG-Mpg)

[iMichaela]

02/23/2023

I propose creating a new issue around how to best tell the story (AJ's proposal) and spike it in the next sprint. I am planning to create the ADR after the status meeting, to give it a last chance to be reviewed. If we agree to this approach, I will cancel the meeting to discuss #1496 part 2 we have today.