Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add initial change set docs #3185

Conversation

samuelstroschein
Copy link
Member

@samuelstroschein samuelstroschein commented Oct 22, 2024

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

Copy link

changeset-bot bot commented Oct 22, 2024

⚠️ 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

@samuelstroschein

This comment was marked as outdated.

@NilsJacobsen
Copy link
Member

@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:
image

@NilsJacobsen
Copy link
Member

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
Copy link
Member

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
Copy link
Member Author

@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"

CleanShot 2024-10-23 at 09 30 44@2x

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
Copy link
Member

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

@NiklasBuchfink
Copy link
Member

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

@felixhaeberle
Copy link
Contributor

felixhaeberle commented Oct 23, 2024

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
Copy link
Member Author

samuelstroschein commented Oct 23, 2024

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

@samuelstroschein samuelstroschein merged commit c20f4b9 into lix-integration Oct 23, 2024
2 checks passed
@samuelstroschein samuelstroschein deleted the lixdk-208-write-initial-change-set-documentation branch October 23, 2024 15:28
@github-actions github-actions bot locked and limited conversation to collaborators Oct 23, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants