Project setup requirements collection

[kettei-sproutty]

In our pursuit of creating a streamlined and efficient project setup, it's crucial that we gather and organize our requirements systematically. This discussion aims to outline the fundamental technologies, strategies, and best practices that should be considered as we embark on setting up our project. To avoid scope creep, we should primarily focus on defining the requirements for a minimum viable setup while welcoming innovative ideas for future enhancements.

Please contribute to this discussion by creating sub-threads for specific technologies, tools, or strategies that you believe should be included in our project setup.

[kettei-sproutty]

Changelog

We should create a github action that generates changelog for each package, following Conventional Commits standards.

Considering <type>[optional scope]: <description>, in conventional commits standards, we should make optional scope as mandatory, referring to the package/app that was updated.

• We should ensure that commits are only related with one scope.
• We should ensure that all commits inside a PR follow this rule.
• We should ensure that before-commit hook would fail if people are committing files of different packages together.

[fra-malagisi]

This repo (https://github.com/changesets/changesets) could be for us. I've seen it used by big projects like pnpm and astro and it's easy to set up.
we could try 🙂

[dan-alin]

We should set a standard for the optional scope either, otherwise we could've changes for the same feature/ file under different scopes.

example:
fix(login): example fix 1
fix(login.svelte): example fix 2

I suggest to use the feature over the file as scope

[kettei-sproutty]

Release, versioning and tags

We should decide how we want to handle releases, tags and versioning, maybe looking at other monorepo projects, and adopting the best strategies that suits our use case.

Release (Branch strategies)

We should decide how we want to handle branches, if we should adopt a trunk-based strategy or another kind of strategy.

Versioning, milestones and tags

We should analyze how we want to handle versioning (related to #Changelog discussion. We should understand how to tag in a monorepo and which conventions we should use.

[lutaok]

We would have two or potentially more apps to handle releases for.
Ideally we should release both together since docs app is strictly related to the main ide app. We all know, though, that docs package could be updated without the need of updating ide package (typo fix, feature integration like potentially a text based search).
I don't actually think pure trunk-based strategy can be beneficial for us, but I don't think Github flow would be ideal either.
What should we represent with each branch?

[fra-malagisi]

IMHO the trunk based strategy could be a good solution for us.
By pushing small and incremental changes we can get some benefits like:

• Avoiding Merge Hell
• Reducing the number of active branches that need to be managed.
• Make it easier to spot potential issues early (since all developers are working on updated branches).
• Constant testing and deployment.

@lutaok I think each branch should represent a feature/fix/etc... and, in some cases, it could include more packages changes.

[kettei-sproutty]

Looking at other projects using monorepos that are using trunk-based strategy such as:

• NextJS
• SvelteKit
• Bun
• Astro

There is one "always updated branch" such as canary or main.
Is possible to handle multiple packages tags, the best example in the links i sent before is SvelteKit.

There is a github action that handle tagging and releasing (PR HERE) for a determinated package:

We should ensure that every PR is labelled with the correct milestone, with examples i like the most are:

• Bevy <- Mostly here
• SvelteKit

From here my ideas are

• Release are always handled by PRs, not by merging in a predeterminated branch.
• Release are always followed by a TAG.
• PRs are merged only if labelled for the next milestone.

This strategy will add a little bit more setup (labels, projects, milestones, actions) but imo is very solid.

[dan-alin]

I agree with @kettei-sproutty , if properly set, the trunk-based strategy would benefit the project by keeping the delivery simple and fast, while having all the control provided by the PR's and the CD/CI

[lutaok]

Yeah, after reading your replies and some more thoughts on it, I agree with you all 😁

[kettei-sproutty]

Code of conduct, Issues, Labels and Contributors

We should create:

• A/Some issues template(s), making more easy for contributors open new issues.
• A code of conduct, avoiding PRs and comments that could be targetted as SPAM.
• Labels that can address better issues and and PRs.
• Contributors file, where we can (or automatically?) add every person that decide to help in this project.

[lutaok]

Yep, agree with this.

We also be mindful of people coming to contribute and leaving comments on issues. We should assign the issue to the first person who shows interest in contributing to it.
We should be careful not to make people work on issues that are already taken.

We also must establish a flow to make the issue available again when no work has been done and a more or less long period of time has passed.
What do you think could be a reasonable time? I suggest a month if the issue has medium to low priority and two weeks for the medium to high priority issues.

This make me think: we also should label issues with priority tags, do you think it could be valuable?

[dan-alin]

Using priority tags on issues is a good idea. I'm fine with the suggested times, but we should manage even a higher priority,in order to handle urgent issues, maybe something like:

• lowest/low 1 month
• medium: 3 weeks
• high: 2 weeks
• highest: ASAP

Do you think that might work?

[lutaok]

Yeah, I think this sounds great.

I previously said

when no work has been done

How should we manage the case work has been done on an Issue, the PR has been reviewed, but the potential contributor hasn't been able to further work on the reviewed PR?

I know that maintainers have rights to co-author PR, so maybe one of us could intervene in that case. Maybe that's something that should be evaluated case by case when (if) it happens.
I am looking forward to know what you think about it!

[kettei-sproutty]

Handle dependencies, Node and Package Manager version

• We have to assure that our depdendencies are (weekly/monthly) updated to the latest version, with tools such as Dependabot.
• We should always try to use the latest Node@LTS version (when depdendencies give us the opportunity).
• Using bun (that is so fast moving), we should try to update it as often as possible so we can benefit of it the most.

• We should try to avoid having multiple packages with different version.
• We should try to ensure that every person use the same Engine and Package
• We should try to ensure that when we change version of Node/Bun, we reflect that change in all project (example: package.json and CI)

[lutaok]

I agree.
I think we also should have a supported environments section, so we should try to experiment more runtime/dependency versions in order to assure compatibility.

[kettei-sproutty]

We could even create a GH action that will ensure compatibility for different environments.

[lutaok]

Communication Channel

We should you use one communication channel where we could:

• Interact with the future community and help when possible on support issues
• Have a centralised place where GH issues are notified
• Have private group chat where maintainers can discuss on minor topics which don't need community involvement

I suggest Discord as a communication channel because it integrates with GH issues and other providers.
It also seems that most open source communities are on Discord, so users are used to it.

[kettei-sproutty]

I agree on everything, Discord in my opinion is the best choice too.
We can use Discord even for notify about new version release (maybe with some bot?).
Another thing, i think for users should be easy to reach our communication channel (maybe updating README with a direct invitation link).

[fra-malagisi]

Discord is the best option in my opinion. Good idea the link in the read.me, easiest way to find the channel

[kettei-sproutty]

As everyone agree on using Discord as comminication channel, i'm gonna convert this sub-thread as issue. Feel free to assign it to yourself and update the README opening a PR.