search

bootstrap-vue-next / bootstrap-vue-next

Early (but lovely) implementation of Vue 3, Bootstrap 5 and Typescript
https://bootstrap-vue-next.github.io/bootstrap-vue-next/
MIT License
1.13k stars 117 forks source link

Generate a parity list report #1775

Open VividLemon opened 9 months ago

VividLemon commented 9 months ago

Clear and concise description of the problem

In order to release v1, a parity list spreadsheet needs to be created for internal use. A list comparing the feature set of bv to bvn, including: props, emits, and functionality.

This is vital to the release of the library as we need to be able to properly index what is missing and what is simply removed behavior.

Even things that are declared deprecated in bv should be noted on the parity list, but have a comment describing they are deprecated.

An online spreadsheet (please do not post direct files here, for security) as an evolving spreadsheet.

Suggested solution

An online spreadsheet should be created here to document every components parity with that of bv. It should contain information about prop differences, (say if bv had type "string" and we had type "sm" | 'md' | 'lg'. It's not invalid, but it needs to be documented)

Alternative

This needs to be finished by the time v1 is released

Additional context

No response

Validations

VividLemon commented 9 months ago

Note: this is related to https://github.com/bootstrap-vue-next/bootstrap-vue-next/issues/1780 , in addition to a parity list with bvn, we must also review new features that were added to Bootstrap v5, that have not been implemented in bvn.

For example, stripedColumns were an addition to bootstrap v5, but weren't added until like v0.12. These things need to be documented as well.

dwgray commented 9 months ago

I've taken a stab at creating a spreadsheet for tracking parity/completion of features. I hope the spreadsheet is self-explanatory, The first tab is definitions, and the second is the actual tracking.

Design decisions, which I'm happy to take feedback on:

  1. I'm just covering components now. I believe other things will have somewhat different schemas and could be represented by different tabs, but if we get a good handle on components and their documentation that will get us 80% of the way there.
  2. Granularity - Possibilities
    1. One row per component - this seems light. If we want to do this level, it would make more sense to have an issue per component, possibly with a different template
    2. Row per component, property, event, slot, with room for extra rows if there are things about a component that need to be called out. This is where I landed.
    3. In addition to the above, also have rows for event arguments, slot-scoped properties, etc. This feels like it will make the schema too complex and would be unmanageable
  3. I used Excel on OneDrive, since that's what I'm most familiar with. Happy to move to a different system if there is a strong sentiment/good reason to do so.

A read only version of the spreadsheet is here: https://1drv.ms/x/s!AiUqzkjNYGL6ieBPpQpcR41wo1laZQ?e=DYykFl - I'll share write access to contributors once we get things locked down.

image

image

P.S. I posted something like this yesterday. When I looked at it again it looked like GitHub duplicated it, so I deleted the duplicate. But it appears that it disappeared. So, if the apparent duplicate was someone quoting and commenting, I apologize and hope I didn't delete too much information. Please go ahead and repost, and I promise not to delete it again….

VividLemon commented 9 months ago

Please go ahead and repost, and I promise not to delete it again….

It's unlikely that you'd be able to delete other persons posts. I wouldn't worry about it. Regardless, all events are sent to my email, so I can see that nobody else had made a response. So, this is a non-issue.

The format looks good, this is likely how I would do it. Do keep in mind that very soon https://github.com/bootstrap-vue-next/bootstrap-vue-next/pull/1791 will be merged. So, some component definitions may change

dwgray commented 9 months ago

The format looks good, this is likely how I would do it. Do keep in mind that very soon #1791 will be merged. So, some component definitions may change

Thanks - my next step is going to be to see if I can figure out an automated way to populate the spreadsheet with the BSV Legacy information, that seems like it would give us a good framework. I think we probably want human eyes when filling in any of the BSVN information so I'm less convinced that automating that makes sense, but I'll think about that while I get the BSV Legacy step in.

dwgray commented 9 months ago

I populated the parity spreadsheet with the bootstrap vue legacy information (nearly 2000 rows) and over 100 components! I wrote automation to do this, and I believe I got everything, but could use another set of eyes to check if I missed anything obvious.

I then went through and filled in the rows for BFormCheckbox and BFormCheckboxGroup since those are components that I've fixed bugs in and updated documentation for recently; note that I filled this out with the assumption that #1791 had already been done.

I added a tab to the spreadsheet with instructions, which includes the process I used as a suggested process. I'm happy to refine that based on suggestions from others with more experience. Also interested if I missed anything big.

image

Things that still need to be decided before using this to evaluate more components:

Do we want to auto-populate the BSVN columns? I'm leaning towards no. I feel like the person filling out a component is going to be spending enough time reconciling the various places where items are used/defined/documented that manually adding these cells won't be much of a burden. But it also won't be too hard to generate this data - the most challenging part might be weaving the two sets of data together.

I think we'll want to consider what to do about things like button-variant and models. These are things where we generally have parity but are handled a bit differently in BSVN. I would suggest that we write a general discussion of these differences in the migration guide, then when going through this spreadsheet, if that general discussion seems to cover the difference, mark the migration column "Not Needed." If that makes sense, I'll add an issue/issues for documenting each of these general issues in the migration guide (and then see if I can find time to do a first pass at them).

How thorough do we want to be about documenting types? There are several types used in these components that don't show up in the types documentation; should we track that here as well?

How do we want to open up access to this? I think I'd be all right with just publishing an editable link to this spreadsheet would be easiest. OneDrive manages versioning, so if a bad actor or an over-enthusiastic novice messes it up, I can just go back to a previous version. Alternatively, I can add specific users to write access. Let me know.

VividLemon commented 9 months ago

How thorough do we want to be about documenting types? There are several types used in these components that don't show up in the types documentation; should we track that here as well?

Likely https://github.com/bootstrap-vue-next/bootstrap-vue-next/issues/1585 should be reopened. If they're used, they should likely be exported.

How do we want to open up access to this? I think I'd be all right with just publishing an editable link to this spreadsheet would be easiest. OneDrive manages versioning, so if a bad actor or an over-enthusiastic novice messes it up, I can just go back to a previous version. Alternatively, I can add specific users to write access. Let me know.

This is a good question with no great answer. Github does not have any builtin way to make an excel sheet, which makes sharing around difficult. Likely only myself and @xvaara need access. Although, anyone that I suppose comments here could also be given access

Alternatively, it may be best to have each file be readonly, where anyone that wishes to make a change would download the sheet, make modifications, then reupload to this thread. However, I do wonder if there's security issues involved with this.

Overall, very good work. I don't have any specific mentions about the structure or anything else. Migration is definitely more difficult when we have three different places of changes (bootstrap, bv, & vue). Thank you

dwgray commented 9 months ago

How thorough do we want to be about documenting types? There are several types used in these components that don't show up in the types documentation; should we track that here as well?

Likely #1585 should be reopened. If they're used, they should likely be exported.

Do we also expect that every exported type is documented on the types page? I would say yes. In which case, maybe we can keep it simple and make verifying that part of the docs complete bar?

How do we want to open up access to this? I think I'd be all right with just publishing an editable link to this spreadsheet would be easiest. OneDrive manages versioning, so if a bad actor or an over-enthusiastic novice messes it up, I can just go back to a previous version. Alternatively, I can add specific users to write access. Let me know.

This is a good question with no great answer. Github does not have any builtin way to make an excel sheet, which makes sharing around difficult. Likely only myself and @xvaara need access. Although, anyone that I suppose comments here could also be given access

Alternatively, it may be best to have each file be readonly, where anyone that wishes to make a change would download the sheet, make modifications, then reupload to this thread. However, I do wonder if there's security issues involved with this.

So it turns out that onedrive will let me create a separate read/write link that I could share privately with you and @xvaara and you could share out with others at your discretion. I could also delete that link if it leaks for some reason. Seems like a decent solution if you're both good with that. Excel Online is getting pretty good, so you probably don't have to download the file, but if only the three of us have access, it's probably not a giant security risk. Let me know your preferred channel for me to send you the link - it looks like there is a little used Discord server for this project, so I could DM you on Discord (I saw Xvaara's handle show up in the general channel, but it wasn't obvious what yours is).

Overall, very good work. I don't have any specific mentions about the structure or anything else. Migration is definitely more difficult when we have three different places of changes (bootstrap, bv, & vue). Thank you

Thanks!

euoia commented 8 months ago

What is the best way to contribute updates to the parity report? I just had a quick look and the bTable items prop shows a type of Array but it can (importantly) be an Array or a Function.

image image
dwgray commented 8 months ago

What is the best way to contribute updates to the parity report? I just had a quick look and the bTable items prop shows a type of Array but it can (importantly) be an Array or a Function.

Good catch, @euoia . This is a general bug in the scraper that generates the initial report. I'll fix it and put a revised version up for review.

More broadly - My guess from his comments on this thread is @VividLemon originally intended this to be something that he and the other maintainers (I think that might just be @xvaara at this point) could use to run through all the features before calling v1 complete.

On thinking about this a bit more, my proposal is to open this up to any contributor who is willing to spend the time to dig through the code and docs to fill out the parity report in a way similar to what I did for BFormCheckbox. If @VividLemon is all right with that, I'll add columns for the last contributor review (which would be a github alias and date) and last maintainer review (again, alias and date). Then, contributors could take ownership of the rows for a component and do a bunch of the initial legwork, which would let the maintainers spend much less time doing a final pass.

In any case, I would appreciate some more eyes on the initial report before we open it up to editing, because it will be much harder to correct this kind of mistake once others have contributed.

dwgray commented 8 months ago

@euoia I reuploaded the parity spreadsheet with the new data which includes the "union" types. I looked through the BTable section and things appear to line up. Please let me know if you see anything else I missed. Thanks!

VividLemon commented 8 months ago

All of the last comments are things I agree with. For some reason I've been forgetting about this, and didn't realize that it had gotten so old. I am okay with a general spreadsheet being passed around. It seems like the quickest way to have this issue fixed, as this is very high importance for the prospects of v1. Seems loosening restrictions is a necessity for quickness. The only reservations I have are those security related in excel itself. And you never really know with it being truly open. But it seems like a low risk high reward situation, if any risk

My discord is @templeos

dwgray commented 8 months ago

I've put up a PR to update contributing.md to point folks at the feature parity spreadsheet (and hopefully get more folks to contribute to it). If this looks good, I'll add a pointer to that in the "how can I help" and "when is this going to be released" threads.

dwgray commented 8 months ago

@VividLemon - discord wouldn't let me DM you with the password for the r/w version of the spreadsheet. I sent you a friend request, my handle is @ohdwg, which seems like you may require to DM?

VividLemon commented 8 months ago

Deprecation note https://github.com/bootstrap-vue-next/bootstrap-vue-next/pull/1830#issuecomment-2032773290

VividLemon commented 8 months ago

Deprecation note https://github.com/bootstrap-vue-next/bootstrap-vue-next/issues/1798#issuecomment-2032781026

VividLemon commented 6 months ago

Deprecation note BTable modelValue -> @change event

dwgray commented 5 months ago

Based on this discord discussion it looks like some people are finding the parity report and using it to assess where the project is. I added some text in a couple of places to try to discourage this until we've gotten farther along. However, people don't always read the docs :-) So I spent some time going through the top-level components and getting their status updated to the best of my ability. Hopefully that will help as well...

Most of the in-progress components that I've looked at are pretty close (although documentation is generally lagging) - that's 90 components! Of the remaining 24 components, I'm think at least 8 are intentionally deprecated and there are a couple of clusters of components that probably don't need to be implemented for a v1 (BMedia and BSkeleton) - in fact I'm not sure any of them are really needed for a reasonable v1, I'd put the more systemic issues that @VividLemon is tracking in the project above any new components.

VividLemon commented 5 months ago

Deprecation note BTable 'selected' event => @update:selectedItems

VividLemon commented 5 months ago

I'm not sure any of them are really needed for a reasonable v1, I'd put the more systemic issues that @VividLemon is tracking in the project above any new components.

The only issue with v1 is stability. Not necessarily compatibility.

I will be looking closer at this issue soon

VividLemon commented 4 months ago

BFormFile with various changes to what you can set to the input https://github.com/bootstrap-vue-next/bootstrap-vue-next/issues/2052 . Notably setting value to []

VividLemon commented 1 month ago

html props are removed https://github.com/bootstrap-vue-next/bootstrap-vue-next/pull/2311