Formik: Establishing Issue Organization Guidelines

[johnrom]

The goal of this organization is to

• highlight discussions of importance to the community
• prioritize work so that maintainers can spend their limited time wisely
• establish exactly what work is required for a given release

This proposed organization is loosely based off of open source projects like:

• https://github.com/aspnet/AspNetCore
• https://github.com/OrchardCMS/OrchardCore

1. Organize current issues by milestone, to cancel out the noise of those things not currently on deck. Recommended Milestones:
   
   
   
   • [x] v1.x hotfix: bugs or small features that should be addressed now as they affect the community
   
   
   • [x] v2.0: _only_ those issues which are prioritized for v2 launch
   
   
   • [x] backlog: bugs or features that do not need to be addressed by v2, but should be fixed after and before thinking about the ideal features in vNext. these should eventually be prioritized into v2.1, v2.2, etc milestones
   
   
   • [x] vNext: features which are important to the project, but depend on v2 launch and should not coincide with it or even be thought about regularly
   
   

Future prioritization looks like:

backlog -> v2.1, v2.2, v2.3
vNext -> v3 or backlog after v3 release, v4

1. Remove or lock Umbrella issues because they become an endless stream of weird feature requests and issues. All Umbrella issues should link to either a Focus Label or a Milestone, and when they are determined to be actionable, should belong to a version milestone like v2.0.

• [x] v2 Umbrella Issue #828
• [ ] React-Native Umbrella #1444
• [ ] Improving Field #1371
• [ ] New Examples / Sandbox #1315

1. Standardize Labels
2. I recommend removing certain types of Labels
   
   
   
   • [x] Remove version tags, as they belong to milestones.
   
   
   • [ ] Remove Component labels (new Focus: Components), as they are noisy and probably will cause changes to other Components anyway.
   
   
   • [x] Remove Browser: Chrome and similar labels, as these are more implementation details that should be written under the issue.
   
   
3. Most other labels should be prefixed
4. Discussion: When an issue is attempting to be prioritized by the community.
5. Priority: Establish the importance of an issue to a milestone
   
   
   
   • Required (High, Medium)
   
   
   • Icing on the Cake / Optional: Those things which could be kicked to the next milestone, if warranted.
   
   
6. Focus: Establish the general area of work (similar to current Components)
   
   
   
   • [ ] Components (currently Fastfield, Field, FieldArray, Form, Formik)
   
   
   • [x] TypeScript
   
   
   • [ ] React Native
   
   
   • [ ] Documentation
   
   
   • [ ] Examples
   
   
   • [ ] Testing
   
   
7. Status:
   
   
   
   • Needs Browser Testing
   
   
   • Completed (currently "done")
   
   
   • In Progress
   
   
   • Help Wanted
   
   
8. Resolution (existing)
9. Type (existing)
   
   
   
   • maybe remove Umbrella because that should be established by Milestones
   
   
   • maybe keep Umbrella but keep it locked and as a pointer to the milestone, since milestones aren't always obvious to the community on Github
   
   
   • add Type: Cross-Browser inconsistency if you want to preserve "Browser: Chrome" like labels
   
   

10. Other (no prefix)

    • Stale
    • Good First issue
    • Pinned

11. Add this information to the Contributing docs and establish guidelines for successfully prioritizing issues using labels and milestones.

[Andreyco]

Awesome idea!

[jaredpalmer]

Sounds good.

[Andreyco]

Are there any actions to be done done? The sooner this is done, the better. At least some of those points

[johnrom]

I think I'll have some time this weekend to get this kickstarted, though I would like to know if you guys have any revisions / alternate ideas on anything before I get started

[Andreyco]

I am seeing a lot of v2 related Issues open - whether they are issues of ideas, doesnt matter. To get v2 shipped, we should focus on those first and this would be great starting point - having a timeline, bucket of deal breaking issues and ideas which we can deliver later (new features does not need to ship with 2.0)

As part of this, we should go thru issues and triage them. And clean/merge issue labels.

[johnrom]

Agreed. The goal is to get _every_ issue into a milestone, so that it's clear when an issue hasn't been looked into yet.

I think the first step is finalizing the content of this issue, and adding it to the .github/CONTRIBUTING.md file so that current and future maintainers and community members understand the process, and revisions to this process can be version controlled.

[jaredpalmer]

Don’t make a mess 😂😂

[jaredpalmer]

But yeah this is fine

[johnrom]

If I have time to implement this weekend, I will not perform any changes that don't exist already. I will rename labels except those that remain the same, and make sure those updated labels apply to the issues as they currently exist. I will move anything marked [v2] or labelled 2.0 into the v2.0 milestone, but I'll leave everything else unprioritized as I'm not knowledgeable enough about the codebase to decide how important most of these items are to the community.

[jaredpalmer]

Sounds awesome! You rock!

[johnrom]

I had a thought about this today as some issues were pouring in. Some issues are more like "questions regarding v2" and not necessarily actions that need to be taken toward the milestone. So I think we should remove the "2.0" label (since it denotes a specific version), but add a "v2" label referring to the general API around v2 as it's materializing. The label will allow us to go back and see an overview of questions related to the v2 API, and repeated questions will give us information about what API design can be improved.

I'm also wondering if it might be better to switch the Stale bot to only react to issues with a specific label (or set of labels), like "awaiting author response", "Resolution: Needs more information", since long running issues are often just waiting on external dependencies (like v2). It seems like sometimes automatically closed issues cause more work because somebody has to comment and then we have to re-open them. Some automatically closed issues might even be issues that the maintainers expect to work on, but now won't see on deck because it was automatically closed.

Examples of issues where I can't tell if they were closed intentionally or not:

• https://github.com/jaredpalmer/formik/issues/746
• https://github.com/jaredpalmer/formik/issues/812
• https://github.com/jaredpalmer/formik/issues/389

[johnrom]

I had some time today, so I did the following:

• Issues from label 2.0 which I determined to belong to v2.0 instead of the v2 api label were moved to the v2.0 milestone.
• I renamed the label 2.0 to v2 to mean questions and issues surrounding the new API, and not necessarily the version 2.0.
• Renamed "Browser: Chrome" to Type: Browser Inconsistency
• Renamed "TypeScript" to "Focus: TypeScript"
• Locked v2 Umbrella Issue #828 in support of the Milestone

I held off on renaming things like help wanted or done in case they have special meaning to the github repository. I'll need @jaredpalmer 's feedback on whether that's the case.

I'm going to pause before doing more to get your feedback on how the new system is working. Let me know!

[sw-yx]

not stale