Discreta Documentation

A repository of all documentation for general repository rules and style guides.

Style guides

Consistent style guides have been made for each part of the app. They are to be followed by all contributors while making PRs to the main repository.

License

This repository is licensed under GNU GPL v2.0. You can check it here.

Git Guide

The following is a general guide to using git and github to contribute to Discreta.

Commit Styling

Commits must be styled as <action>: <description>. Here are some examples: fix: Code styling in frontend., ci: Add test runners., feat: Add more games., etc.

Contributing

Contributors are to fork their respective team's repo into their personal accounts and create a feature branch for the features they are working on to contribute to the team's repository.

Example:

If the contributor is working on a feature called poset_game or something along those lines, they would fork their respective team's repo (please contact your team coordinator before you do this just to make sure you are forking the correct repo) and make a new branch on their fork named feature/poset_game and start working by importing only the contents of that branch into their local system (can be done very easily in VSCode, you can refer online for more info).

Refer here for a guide on creating forks on GitHub.

After creating the fork on your personal Github account, you can clone the repo to your local by opening a command prompt or terminal and typing in:

git clone <link to your github repo>

Here the <link to your github repo> should be replaced with the link. Eg: https://github.com/sathya-pramodh/seedqueue which is a fork of https://github.com/kingcontaria/seedqueue.

Now you are ready to make changes, open up VSCode (or your favourite IDE) and open this cloned repository inside of it.

Once you are done editing, you can push your code to a new feature branch in your repository by opening up a terminal in VSCode and typing in:

git push -u origin feature/<feature name>

Here the <feature name> has to be replaced with whatever feature you are working on. Eg: feature/poset_game.

This will automatically create a feature branch on your fork and you can make a Pull Request to your team's repo from this branch by clicking on the Contribute button while in the branch that you just created on GitHub.

Drafting a PR(pull request) is also very essential in letting the maintainer know what your code does so please make sure to follow the guidelines below.

Pull Request guidelines

A pull request must follow the same title styling as the commit styling, i.e., must be styled as <action>: <description>. Here are some examples: fix: Code styling in frontend., ci: Add test runners., feat: Add more games., etc.

For most feature additions, it can be styled as feat: Add <feature_name>. where the <feature_name> is replaced with the actual feature name. Eg: feat: Add poset_game..

In the description of the pull request, contributors should add relevant changelogs as separate points. Eg:

# Changelog
- Refactored `TitleBar` component into a separate file.
- Fix coloring not working in `App` component.
- Fix API endpoint `/api/get-game`.

Any other comments like breaking changes can also be added under the changelog under a separate heading called # Breaking Changes, for example.

Issue Guidelines

The following document is a general guide on creating issues and fixing issues in Discreta.

Creating issues

Issues and bugs that are found by testers must be created on the team's repo and must be fixed by the team before contributing to the main repo.

Issues must include some important headings like so:

# Description
Your issue description and relevant screenshots go here. You can even include the commit that introduced this bug here.

# Steps to Reproduce
A set of steps that you can perform to reproduce this issue goes here.

# Suggestions for potential fix
Your suggestions on what could be done to fix it goes here. (this is not compulsory)

# Suggested Assignee
You can suggest assignee(s) to this issue if you'd like. This will most likely be the contributor(s) who pushed the commit listed above in the description.

Fixing issues

If you are looking to fix an issue, first create a fork of the team repo for yourself (if you are a contributor already, you can skip this step).

Now create an issue branch as issue/<issue number on the repo> where <issue number on the repo> is replaced with the issue number. Eg: If you are trying to fix issue #8 on your team's repo, then you'd name your branch as issue/8.

You can now commit code to your issue branch to fix the issue completely and then make a pull request to the team's repo for the same.

Timeline guide

The following document is a general guide on what the timeline of Discreta is going to be for every week.

Merge window

The Merge window is a strict deadline every week before which all code must be merged into your team's repo and the PR from the team's repo should be made to the main repo.

The merge window per week is going to be from Wednesday of the current week to Monday of the next week.

All contributors and coordinators are requested to make sure that they finish testing and merging code to the main repository by Monday of the next week.

The days Monday, Tuesday and Wednesday are taken to fully test how well the new code integrates with the entire codebase and fix any issues that come up during those tests.

This would make sure that the code being finalized by Wednesday is completely bug-free and is ready for showcase to the professors.

Frontend Style Guide

The following is a general style guide for the frontend of Discreta.

Code formatting

Code formatting must be done with Prettier. Ensure that all code is formatted before making PRs or commits to main repositories.

Component styling

New components must be added into the components/ directory. They have to be named in Pascal Case.

The Component's filename must match with the component name itself. Eg:

const BaseComponent = () => {
    return (
        <>
            <h1> Hello World! </h1>
        </>
    )
}

export default BaseComponent

The above contents would be saved in a file named BaseComponent.jsx.

A component should be made if a particular part of your UI is re-used more than once. Eg:

const TitleBar = ({ title }) => {
    return (
        <>
            <div>
                <h1> {title} </h1>
            </div>
        </>
    )
}

export default TitleBar

The above component can be re-used over and over with only the title being changed per use. So refactoring it into a component makes sense here.

Components have to be functional only. Do not use class components. Refer more here. They also have to be arrow functions.

A component has to be made within a .jsx file only. Do not use a .js file and import { React } from "react" every time. A consistent format for a component has to be maintained as follows:

// Put your imports here.

const ComponentExample = (props) => {
    return (
        <>
            <div>
            </div>
        </>
    )
}

export default ComponentExample

Always start your component's return with an empty tag. This is to make sure that adding new children doesn't need a full refactor of the entire component structure.

const HomePage = () => {
    return (
        <>
            <h1> Hello World! </h1>
        </>
    )
}

If the tag is short enough along with its contents and styling, they can be on a singular line as:

<h1>Hello World!</h1>

But if its large enough, it has to be multi-line as:

<parent-tag>
    <tag-child-1/>
    <tag-child-2>
        lorem ipsum dolor
    </tag-child-2>
</parent-tag>

Tags without any content inside it must be started and ended at the same time as:

<img src="" alt="" className=""/>

Do not end lines with semicolon.

Images must be imported in the javascript and not used as a filepath source.

import { IconExample } from "./icon.png"

const ImageComponent = () => {
    return (
        <>
            <img src={IconExample} alt="Icon Example"/>
        </>
    )
}

export default ImageComponent

CSS must also be directly imported in the javascript and not linked in the component's HTML.

import "./index.css"

CSS of a component must be named the same as the component's file itself.

import "BaseComponent.css"

const BaseComponent = () => {
    return (
        <>
            <h1> Hello World! </h1>
        </>
    )
}

export default BaseComponent

A blank line is to be maintained after the block of import statements and the component function's end.

Variable naming

Variables have to named in Camel Case.

const exampleVariable = "Hello World!"

Variables used in the useState hook must follow the following consistent style. The setter function must be named as set followed by the variable name all written in Camel Case.

import { useState } from "react"

const UseStateExample = () => {
    const [stateVar, setStateVar] = useState(true)

    return (
        <>
            <h1> {stateVar} </h1>
        </>
    )
}

export default UseStateExample

Variable declarations within the function must be in a block, followed by a blank line after all the variables are declared.

Backend Style Guide

The following is a general style guide for the backend of Discreta.

Code formatting

Code formatting must be done with Black. Ensure that all code is formatted before making PRs or commits to main repositories.