[GODRIVER-2687] Deprecate "NewTagSetFromMap" and "NewTagSetsFromMaps" in tags package Created: 11/Dec/22  Updated: 27/Oct/23  Resolved: 27/Apr/23

Status: Closed
Project: Go Driver
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Unknown
Reporter: Matt Dale Assignee: Matt Dale
Resolution: Works as Designed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Epic Link: Go Driver 2.0 Prep
Quarter: FY24Q1
Documentation Changes Summary:

1. What would you like to communicate to the user about this feature?
2. Would you like the user to see examples of the syntax and/or executable code and its output?
3. Which versions of the driver/connector does this apply to?


 Description   

The NewTagSetFromMap and NewTagSetsFromMaps functions may mislead users into expecting that the ordered tag.Set type can be created from a Go map, when in fact the resulting tag.Set has a non-deterministic order. Deprecate those functions in preparation for them to be removed with v2.0.

Note that users can safely define ordered tag sets using a syntax like

set := tag.Set{{Name: "name", Value: "value"}, ...}

However, that's a bit verbose for longer tag sets, so we should consider adding a convenience function that takes in a list of tag tuples and creates a Set, returning an error if the list length is odd.

func ToSet(tags ...string) (Set, error)

Since that requires users to handle errors, and we typically expect users to define this statically in code, we should also consider adding a shorter convenience function that panics on any errors (inspired by Go's template.Must).

func Must(Set, error) Set

Definition of done:

  • Deprecate NewTagSetFromMap and NewTagSetsFromMaps
  • Consider adding convenience functions for creating a Set


 Comments   
Comment by Matt Dale [ 27/Apr/23 ]

Actually, there's nothing to fix here! Tag sets, which are sets of key/value pairs, are not order-dependent. Tag set lists are order dependent, but the Go Driver tags APIs always use ordered types, so there shouldn't be issues.

The tag filtering documentation, both in the readpref and tag packages, could be better. However, I'm closing this ticket as there's nothing we need to deprecate.

Generated at Thu Feb 08 08:39:09 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.