Write a brief contributor guide with best practices

[fozziethebeat]

Key things to detail:

1. How to communicate someone is working on an issue
2. How to handle rebase vs merge from main -> working branch
3. pre-commit & why

[fozziethebeat]

We can also tl;dr this post: https://timwise.co.uk/2019/10/14/merge-vs-rebase/

[AbdBarho]

I do agree with the 'rebase first' approach, and I also agree that too many conflicts that make rebases hard usually means the PR is way too big.

Perhaps one other thing that I am biased towards is to always squash merge PRs (I also prefer no merge commits). The history on main is perhaps not as detailed as it could be otherwise, but it is very clean, and it guarantees that every commit on main is functional and deployable (maybe not 100%, but close enough).

[andreaskoepf]

1. How to communicate someone is working on an issue

People should first get assigned before they start working. A developer interested in working on an issues should write in a short comment (possibly asking for clarification if required) and wait to be assigned by a collaborator. (Non-collaborators can only be assign after they commented.)

[Balssh]

People should first get assigned before they start working. A developer interested in working on an issues should write in a short comment (possibly asking for clarification if required) and wait to be assigned by a collaborator. (Non-collaborators can only be assign after they commented.)

Could this be automated in some way?

[yk]

People should first get assigned before they start working. A developer interested in working on an issues should write in a short comment (possibly asking for clarification if required) and wait to be assigned by a collaborator. (Non-collaborators can only be assign after they commented.)

I'd also advocate that for many issues, it makes sense to write down a small plan as a proposal. doesn't have to be long, but it can catch steps in completely wrong directions early

[yk]

Could this be automated in some way?

difficult. naturally, in OSS, anyone can start working on anything at any time. the only manual action in the process is the assignment of the issue, which has to include a manual step anyway, because we have to evaluate case-by-case whether the assignment makes sense or not.

[seyfeddinenecib]

It would be great if the tasks are more clarified in the description with some kind of use case if possible.

[LucianPetri]

I also thought about the folder structure this needs to be discussed since in the web team we are quite many and we will inevitably end up having lots of merge conflicts. This subject may get very long so this should also be a separate thread maybe?

I'll start the contribution over this subject with an option that I battle tested at work. Below are also Pros and Cons and explanatory reasons. We can later use this Example as a template for proposing different Folder Structure options

Folder Structure

Description

At work the teams main duty is to provide primitive/custom components that users will eventually use them in a drag-n-drop fashion to build their interfaces

Our two main concerns are:

1. avoid as much as possible to collide PR files except when pair programming
2. avoid also touching files that need to be tested afterwards over a variety of use cases and edge cases

NextJS ^13.0.0 advantage:

• NextJS 13 introduces a new routing system and will eventually switch in the future to the new app structure so we may want to switch to this as soon as possible since we do not posses too many pages yet.
• This also make every component inside the app folder a server component. Comes with SSR out of the box and best lighthouse scores

Rules to play by

• components SHALL NOT excede a depth more than 4 Tabs in
• components SHALL NOT excede 200 lines except in rare cases
• components are considered BIG if they break the 2 rules above in which case we break it in its /components folder
• components are considered SMALL if they do not break either rule and are kept in a single .tsx file
• No more than 1 component per file
• No multiple exports in component file except for Types/Models
• Components in common usage case: imported in >= 4 Components? move to UI : keep in common folder

General Structure

• I generated this structure using Tree by NathanFriend
• this also contains NextJS 13 app structure

.
└── src/
    ├── components/
    │   ├── UI/ # this will hold basic reusable web components
    │   │   ├── index.ts # import * custom components
    │   │   ├── [Component].tsx # Small Component (Explained below)
    │   │   ├── [Component]/ # Large Component (Explained below)
    │   │   │   ├── index.ts # import * components below
    │   │   │   ├── components/ # component pieces composing a bigger one
    │   │   │   │   ├── [Component].tsx # small Component
    │   │   │   │   └── ...
    │   │   │   └── [Component].tsx
    │   │   └── ...
    │   └── common/ # this will hold custom shared components
    │       └── .. (Same struct as UI)
    ├── hooks/
    │   ├── index.ts
    │   ├── contexts/
    │   │   └── [ContextProvider].tsx
    │   └── use/
    │       └── [useHook].tsx
    ├── app/
    │   ├── Layout.tsx # Shared layout acros multiple pages
    │   ├── Template.tsx # Optional (works similar to Layout)
    │   ├── Error.tsx # Suspense will show this on page error
    │   ├── Loading.tsx # Suspense will show this till data arrives
    │   ├── Page.tsx # Actual Content of the Page
    │   ├── components/
    │   │   ├── index.ts
    │   │   ├── [Component].tsx 
    │   │   └── [Component]/
    │   │       ├── index.ts 
    │   │       ├── components/ 
    │   │       │   ├── [Component].tsx
    │   │       │   └── ...
    │   │       └── [Component].tsx
    │   ├── [Sub-Page]/
    │   │   ├── Layout.tsx
    │   │   ├── Error.tsx
    │   │   ├── Loading.tsx
    │   │   ├── Page.tsx
    │   │   ├── components/
    │   │   │   └── ...
    │   │   └── [Sub-Page]/
    │   │       └── ...
    │   └── ...
    └── styles/
        ├── themes/ # IF USING CHAKRA-UI
        │   ├── ThemeProvider.tsx # Theme and switching Logic
        │   ├── [LightTheme].tsx
        │   ├── [DarkTheme].tsx
        │   ├── [CustomTheme].tsx
        │   └── ...
        └── colors/ # IF USING STITCHES/Styled-Components
            ├── [LightColors].tsx
            ├── [DarkColors].tsx
            ├── [CustomColors].tsx
            ├── stitches.config.ts # Theme and switching Logic
            └── ...

( Taken from NextJS Documentation )

Explanations

• generally we create first a suite of basic components with Chakra to apply our theming
• the common folder is usually dangerous so we limit how much the components are used
• Big Components usually create merge conflicts so we break it in multiple components
• Small Components are the usual custom component that follow all rules
• index.ts is OPTIONAL but recommended to keep imports relative and clean ( also good for tsconfig paths )

Pros

• We avoid conflicts between each other when working on different features on the same page

Cons

• Prepare to have lots of files in the project

[fozziethebeat]

I've moved the web focused discussion to https://github.com/LAION-AI/Open-Assistant/issues/99