Add docs structure

[ribeiroth]

Description

• Add docs folder structure
• Issue: Create Docs folder in the project #40
• Issue: Glossary of relevant terms for project #45

[danctorres]

Cool stuff, but IMO, we can use the proposals directory instead of the agreements

[danctorres]

Adding a commit fixing another commit is a little redundant. Can you squash them so that every commit is relevant, this is only has the intended changes. This helps keep the history cleaner and easier to follow 😄

[ribeiroth]

Adding a commit fixing another commit is a little redundant. Can you squash them so that every commit is relevant, this is only has the intended changes. This helps keep the history cleaner and easier to follow 😄

@danctorres I usually squash when I merge a PR. Of course when we have a big PR is interesting do that, otherwise squash and merge works fine

[danctorres]

Adding a commit fixing another commit is a little redundant. Can you squash them so that every commit is relevant, this is only has the intended changes. This helps keep the history cleaner and easier to follow 😄

@danctorres I usually squash when I merge a PR. Of course when we have a big PR is interesting do that, otherwise squash and merge works fine

I understand your point. This is actually a nice discussion to have and establish a convention for our project, we can have it here. IMO, we want to avoid doing squash and merge or merge commits. Its better to squash it manually, push it, and then rebase and merge, since it makes it easier to review and to follow the history. We want to keep linear history and avoid creating artificial commits. Rebase and merge keeps a cleaner, more organized history and is better when we need to look back at the history.

[ribeiroth]

Adding a commit fixing another commit is a little redundant. Can you squash them so that every commit is relevant, this is only has the intended changes. This helps keep the history cleaner and easier to follow 😄

@danctorres I usually squash when I merge a PR. Of course when we have a big PR is interesting do that, otherwise squash and merge works fine

I understand your point. This is actually a nice discussion to have and establish a convention for our project, we can have it here. IMO, we want to avoid doing squash and merge or merge commits. Its better to squash it manually, push it, and then rebase and merge, since it makes it easier to review and to follow the history. We want to keep linear history and avoid creating artificial commits. Rebase and merge keeps a cleaner, more organized history and is better when we need to look back at the history.

I understand that, if not used wisely, it could lead to some confusion or lack of clarity.
It all depends on how we want to tell the history. For example, I think it’s more useful to have a way to identify the issue in history rather than just the commit, especially when dealing with many business rules. I can see what changed with the commits, but why? Will I remember this in the future?
Your approach doesn’t provide that, although it may not be the case here, so we can give it a try anyway. But yeah, we should discuss this as a team before moving forward 😅

[danctorres]

It all depends on how we want to tell the history. For example, I think it’s more useful to have a way to identify the issue in history rather than just the commit, especially when dealing with many business rules. I can see what changed with the commits, but why? Will I remember this in the future?

Im not sure that I understood your point. Your point is that we are not able to find the project issue with linear history? When we keep a linear history, we can see every commit, and with them we can find the PR that has the issue link. But we can also add the link to the issue in the commit description if necessary. But the underling discussion, why keep a linear history? It makes the main branch cleaner, it's easier to understand, to review and follow changes, if necessary we can easily revert or cherry-pick single commit, easier to find problems with bisect. Sometimes we need to take a look at single commits. With rebase we are sure that we are only changing what we intend, etc.
Here is a references of this discussion: https://stackoverflow.com/questions/20348629/what-are-the-advantages-of-keeping-linear-history-in-git

[ribeiroth]

It all depends on how we want to tell the history. For example, I think it’s more useful to have a way to identify the issue in history rather than just the commit, especially when dealing with many business rules. I can see what changed with the commits, but why? Will I remember this in the future?

Im not sure that I understood your point. Your point is that we are not able to find the project issue with linear history? When we keep a linear history, we can see every commit, and with them we can find the PR that has the issue link. But we can also add the link to the issue in the commit description if necessary. But the underling discussion, why keep a linear history? It makes the main branch cleaner, it's easier to understand, to review and follow changes, if necessary we can easily revert or cherry-pick single commit, easier to find problems with bisect. Sometimes we need to take a look at single commits. With rebase we are sure that we are only changing what we intend, etc. Here is a references of this discussion: https://stackoverflow.com/questions/20348629/what-are-the-advantages-of-keeping-linear-history-in-git

Ah ok, my bad! I was looking for commits without PRs related 😅
I still thinking that depends on the situation, is not a universal true, but well is now rebased and let find out what work for us as a team

[danctorres]

Quick question, do we need the glossary directory? Are going to have multiple files inside glossary?

[ribeiroth]

Quick question, do we need the glossary directory? Are going to have multiple files inside glossary?

Yes, I was thinking of having some files by theme