Consideration for renaming Store.add

[mergesort]

To start, let's look at a small snippet of code.

@Stored(in: .richLinksStore) public var links

public func removeTagFromAllLinks(_ tag: Tag) async throws {
    var linksToUpdate: [RichLink] = []

    for var link in self.links {
        link.tags.removeAll(where: { $0 == tag })
        linksToUpdate.append(link)
    }

    try await self.$links.add(linksToUpdate)
}

---

This code looks perfectly reasonable until you get to the last line, where the removeTagFromAllLinks() method calls call add() on the Store to add links that already exist in the Store. If you were trying to explain this to another developer you wouldn't say you're adding the new links, you'd say that you're updating the old links with updated links.

Due to uniqueness requirements of items in a Store (based on the Store's cacheIdentifier KeyPath parameter) the add method on Store does two things.

1. If an item with a matching cacheIdentifier does not exist, a new item will be added to the underlying Store.
2. If an item with a matching cacheIdentifier does exist, it replaces that item with a new item.

This is the desired behavior for how the Store should work, but not the behavior you would expect with a method named add. In practice I've found myself updating items quite frequently, as much if not more as adding new items, and calling self.$links.add(link) to update items is unexpected unless you understand the semantics.

---

To remedy this I'm considering two options.

1. Add an update function that aliases to add. This would create a clearer API, but one that doesn't provide much of a meaningful distinction. The upside of this approach is that store.update is the most straightforward and communicative name, it would be the most obvious choice for searching through methods in documentation or autocomplete. The downside is that add and update would become interchangeable, so you'd be able to call update when you should call add, or add when update is more appropriate.
2. Add an insert function and deprecate add. This would be a more accurate match the Store's Set-like semantics, though would involve deprecating add. I could do this gradually since it's not urgent, but I'm always hesitant to make big changes without consideration.

Personally I'm leaning towards option 2, but wanted to post this publicly to get the feedback of others.

[mergesort]

After giving this some thought and putting these options before a group of developers and discussing the options at length I've decided to go with option 2, adding an insert function and deprecating add. There was an alternative proposal of changing the name to upsert, and while upsert is most semantically accurate, it isn't very well known in the Apple ecosystem. On the other hand Apple platform developers should be familiar with insert from using Set.

I'll be releasing Boutique 2.1 with a deprecation notice for those using add, nudging people to use insert. The add function will continue working as it has until it is fully removed. The insert function is functionally equivalent to add, which will allow developers to add for insert without changing any behavior. This process will be made even easier by providing an Xcode fixit in the deprecation warning that the user can click to change the function name on their behalf.