add initial change set docs

[samuelstroschein]

Context

Adds initial (!) change set documentation. The docs can be improved later on (!)

Requested feedback

If you have feedback that needs to be addressed before implementing change sets, raise it now. Re question 3 vote in a comment below.

1. Does the concept of a change set make sense to you?
2. Can you improve or even add examples?
3. Naming it change set or change group? Will leave it as sets add initial change set docs #3185 (comment)

https://www.loom.com/share/8f950946d6b74e739c7b534d63a1a351?sid=eb3099c6-0564-4ee6-bdc5-79f5e6d38218

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8239b7f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[NilsJacobsen]

@samuelstroschein I struggle to understand the chart. Why are there two flows that I want to connect? Can you make an example? I saw it more like that:

[NilsJacobsen]

I know we already talked about, that an entity can be in multiple change sets, right?

That would also be a big difference to commits and should be in the document. I would love to see a pro and cons of that approach and a reason why our path is the right one. That will also help the team and devs in the future understand why our system is built like this.

[NilsJacobsen]

Is a change set the only way I can add a discussion/context to a change? Are changes also able to link to a discussion?

[samuelstroschein]

@NilsJacobsen which changes are put into a set is up to the user. the diagram uses two graphs to illustrate that grouping entities is possible.

Entity example with a csv

Every row is an entity. If you make a change to the inventory of all your products (all rows), you likely want to group the changes "updating inventory after closing store on 2022-09-03".

Entity example with inlang

Translating multiple german variants are updates to multiply entities (every variant is it's own entity). If you confirm the changes, you likely want to group all distinct entity updates e.g. variant1, variant2, variant3 in one set "created german translations"

Is a change set the only way I can add a discussion/context to a change? Are changes also able to link to a discussion?

Yes, because a discussion points to N changes. A set can have only one change.

Action items

1. I will add docs for entities
2. I close the discussion around groups vs sets. Sets it is because technically it's the right term and makes more sense when adding a discussion for example.
3. I'll add a comparison to commits section

[NilsJacobsen]

Ahh I see, I was confused by the entity visualization. Because it looks like separate timelines :D

[NiklasBuchfink]

I am in favor of the change group for the same reasons you mentioned as pros

[felixhaeberle]

I do not thinK that we should quickly jump to naming conclusions here. At least not for me as its really crucial people get this primitive. I seeked help from GPT to analyse the meaning & usage of both words in detail.

For example, in maths (given the engineering context) a set and a group are two different things and they belong to different branches and serve distinct purposes. Here’s a breakdown of their differences:

---

1. Set (from Set Theory)

• Definition: A set is a collection of distinct objects, called elements or members. These objects can be anything, such as numbers, letters, or symbols.
• Operation: Sets typically involve operations like union, intersection, and difference, but these operations don’t follow any specific algebraic structure.
• Example:
  A = {1, 2, 3}
  In this example, A is a set containing the elements 1, 2, and 3. There are no rules about combining elements within the set.
• Properties:
  • No structure: Sets don’t have a specific operation (like addition or multiplication) associated with them.
  • Order doesn’t matter: The order of elements in a set doesn’t matter. For example, {1, 2, 3} is the same as {3, 2, 1}.
  • Uniqueness: Each element in a set is unique; duplicates are not allowed.

2. Group (from Group Theory)

• Definition: A group is a set of elements combined with a specific binary operation (like addition or multiplication) that satisfies certain axioms.
• Axioms:
  • Closure: If a and b are in the group, the result of the operation a ∘ b must also be in the group.
  • Associativity: For any a, b, c in the group, (a ∘ b) ∘ c = a ∘ (b ∘ c).
  • Identity element: There is an element e in the group such that a ∘ e = a for any a in the group.
  • Inverse element: For every element a in the group, there is an inverse element a⁻¹ such that a ∘ a⁻¹ = e.
• Example:
  The set of integers (Z) under addition is a group because it satisfies the group axioms:
  • Closure: The sum of two integers is an integer.
  • Associativity: (a + b) + c = a + (b + c).
  • Identity: The number 0 is the identity element since a + 0 = a.
  • Inverse: Every integer a has an inverse -a such that a + (-a) = 0.
• Properties:
  • Binary operation: Groups always involve a specific operation that combines two elements of the group to produce another element.
  • Structure: Groups are more structured than sets due to the additional constraints and operations.
  • Symmetry: Groups often describe symmetrical structures (e.g., rotations, reflections).

Summary of Differences:

Feature	Set	Group
Basic Concept	A collection of distinct objects	A set with a binary operation that satisfies group axioms
Operations	Union, intersection, difference	Defined binary operation (e.g., addition, multiplication)
Structure	No structure	Has structure due to operation and axioms
Examples	{1, 2, 3}, {a, b, c}	Integers under addition, real numbers under multiplication
Duplicates	Not allowed (each element is unique)	Not relevant (focus is on the operation and axioms)
Order of Elements	Irrelevant	May be relevant depending on the operation

---

Outside of mathematics,

the terms set and group can also have different meanings and uses in various fields. Here’s how they differ in common, non-mathematical contexts:

1. Set (General Usage)

• Definition: A set in everyday language refers to a collection of distinct items, objects, or things. These items are usually related in some way, but there is no specific structure or relationship governing how they interact.
• Examples:
  • A set of tools: A collection of different tools used for various purposes, like a hammer, wrench, and screwdriver.
  • A set of dishes: Plates, bowls, and cutlery used in the kitchen.
  • A television set: A term used to describe the hardware unit, but not related to multiple objects.
• Common Properties:
  • Collection: A set is just a grouping or gathering of things.
  • No interaction: The elements of the set don’t necessarily interact with each other in any structured way.

2. Group (General Usage)

• Definition: A group typically refers to a collection of people or things that share something in common or interact together for a common purpose.
• Examples:
  • A group of people: A number of individuals who may interact with each other for a specific reason, such as a group of friends, coworkers, or tourists.
  • A group project: A project where multiple people work together to achieve a shared goal.
  • Social group: People who identify with each other based on social or cultural commonalities, such as a study group, a work group, or a sports team.
• Common Properties:
  • Interaction: In many cases, the members of a group are expected to interact or work together in some way.
  • Common purpose or identity: A group often forms around a shared goal, purpose, or characteristic (e.g., group of fans, work group, etc.).

Key Differences Outside of Math:

Feature	Set (General)	Group (General)
Basic Concept	A collection of distinct items or things	A collection of people or things with interaction or shared purpose
Interaction	No expectation of interaction	Usually involves interaction or cooperation
Common Purpose	No need for a common purpose	Often formed around a shared goal or characteristic
Examples	Set of dishes, set of clothes, TV set	Group of people, work group, group project
Structure	No specific structure; just a collection	Usually more structured, with roles or relationships between members

Contextual Differences:

• In sports, a set could refer to a segment of a game (e.g., in tennis or volleyball), while a group might refer to a team or a bracket of teams competing against each other.
• In music, a set can be a group of songs performed by an artist during a concert, whereas a group can be a band or ensemble performing together.
• In theater or film, a set refers to the physical stage or environment for a performance, while a group could be the cast or crew working on the production.

In summary, while both sets and groups involve collections, sets are generally about distinct items with no required interaction, while groups often involve people or things working together or sharing a common goal.

---

Given this information, do we still thing "change group" applies better than "change set"?
I have a personal preference for "change SET".

[samuelstroschein]

I already concluded that the name change set will remain because it's technically accurate. Thanks for chipping in.