From eaddbfe8f688e887804dc8a15354e2cd5cf713a9 Mon Sep 17 00:00:00 2001
From: Ketasaja <153110145+Ketasaja@users.noreply.github.com>
Date: Mon, 6 Jan 2025 20:01:53 +0000
Subject: [PATCH] Warn about client-side tags being dropped (#967)

## Changes

This behavior can cause unexpected removal of tags added locally.

## Checks

By submitting your pull request for review, you agree to the following:

- [x] This contribution was created in whole or in part by me, and I
have the right to submit it under the terms of this repository's open
source licenses.
- [x] I understand and agree that this contribution and a record of it
are public, maintained indefinitely, and may be redistributed under the
terms of this repository's open source licenses.
- [x] To the best of my knowledge, all proposed changes are accurate.

---------
---
 .../engine/classes/CollectionService.yaml          | 14 ++++++++++----
 .../en-us/reference/engine/classes/Instance.yaml   |  8 +++++++-
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/content/en-us/reference/engine/classes/CollectionService.yaml b/content/en-us/reference/engine/classes/CollectionService.yaml
index 3aefa0382..63d72de06 100644
--- a/content/en-us/reference/engine/classes/CollectionService.yaml
+++ b/content/en-us/reference/engine/classes/CollectionService.yaml
@@ -51,10 +51,16 @@ methods:
       signal created by `Class.CollectionService:GetInstanceAddedSignal()` with
       the given tag.
 
-      **Warning:** When tagging an instance, it is common that some resources
-      are used to give the tag its functionality, e.g. event connections or
-      tables. To prevent memory leaks, it is a good idea to clean these up
-      (disconnect, set to nil, etc) when no longer needed for a tag. Do this
+      ##### Warnings
+      
+      - An instance's tags that were added client-side will be dropped if the server
+      later adds or removes a tag on that instance because the server replicates all
+      tags together and overwrites previous tags.
+
+      - When tagging an instance, it is common that some resources
+      are used to give the tag its functionality, for example event connections or
+      tables. To prevent memory leaks, it's a good idea to clean these up
+      (disconnect, set to `nil`, etc.) when no longer needed for a tag. Do this
       when calling `Class.CollectionService:RemoveTag()`, calling
       `Class.Instance:Destroy()` or in a function connected to a signal returned
       by `Class.CollectionService:GetInstanceRemovedSignal()`.
diff --git a/content/en-us/reference/engine/classes/Instance.yaml b/content/en-us/reference/engine/classes/Instance.yaml
index 57fda7d7e..3965885a2 100644
--- a/content/en-us/reference/engine/classes/Instance.yaml
+++ b/content/en-us/reference/engine/classes/Instance.yaml
@@ -321,7 +321,13 @@ methods:
       already applied. Successfully adding a tag will fire a signal created by
       `Class.CollectionService:GetInstanceAddedSignal()` with the given tag.
 
-      Note that when tagging an instance, it's common that some resources are
+      ##### Warnings
+      
+      - An instance's tags that were added client-side will be dropped if the server
+      later adds or removes a tag on that instance because the server replicates
+      all tags together and overwrites previous tags.
+
+      - When tagging an instance, it is common that some resources are
       used to give the tag its functionality, for example event connections or
       tables. To prevent memory leaks, it's a good idea to clean these up
       (disconnect, set to `nil`, etc.) when no longer needed for a tag. Do this