Skip to content

Latest commit

 

History

History
369 lines (261 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

369 lines (261 loc) · 10.3 KB
Raw

Contributing

When contributing to this repository, please follow the guidelines below. They are based on airbnb's javascript style guide


Table of Contents



General

Naming Conventions

Folder and file names follow the convention of the main element in them. Thus, if it is a component, the convention will be the one of a component. If the main element is a (set of) function(s), files and folders should follow that convention.

Functions

As a general rule, camel case must be used for files and folders.

Incorrect examples:

  • "API"
  • "this_is_a_function"

Correct examples:

  • "api"
  • "thisIsAFunction"

Enums, Interfaces and Types

Enums, interfaces and types should follow pascal case convention with an uppercase letter related to the element.

Correct examples:

  • "EThisIsAnEnum"
  • "EAnotherEnum"
  • "IThisIsAnInterface"
  • "IAnotherInterface"
  • "TThisIsAType"
  • "TAnotherType"

Components and Screens

For React Components, we follow pascal case

Correct examples of objects:

  • "ThisIsAComponent"
  • "AnotherComponent"

We mostly avoid adding index.ts files for each folder. An index.ts is used only for wrapper folders that contain other components.


Folder Structure

To have smaller and better scoped files, we chose to go for the following convention, where a Component or a Screen may have multiple files. The possible files are:

Hooks file

The intent of this file is to host the component's logic. By doing so, we aim to have representational components stored in its corresponding .tsx file and minimize its logic there.


Types file

In this file we put every enum, interface and type we require for the other files to work properly. Remember to follow the convention (here)!


Test files

There won't be a specific file for testing, but rather a folder that will host them. The folder will be called __tests__ and the goal is to keep tests as close to the component as possible. With that, we expect maintenance to be easier and straight forward. More on testing later.


TSX file

This is the main file where the component/screen is defined. Our goal is to make these components as representational and clean as possible, for easier readability and maintenance. This file will connect everything that is defined in the others, to make the component work.


Styles

Styles won't have its separated file and will live next to component's definition. This is due our linter that can only help us out detecting unused styles if they are defined next to the point of use.

Our convention is to name the object as styles and for themed versions, createStyles. It is a good practice to name the returned object of createStyles so that the linter can match the unused styles. To do so, you can do:

export const createStyles = (theme: ITheme) => {
  const styles = {
    ....
  };
  return styles;
};

If a style is a sub-style of another, we generally extract it as a generic style (i.e. horizontalPadding: {paddingHorizontal: 10}) and we concatenate them afterwards in the component:

... style={[styles.horizontalPadding, styles.container]} />

This is decided to keep style sheets small and maximizing the reutilization of them instead of having multiple atomic styles that are used only once.


Components Folder

Components should follow this convention

/Component
   - `__tests__`
      - Component.spec.ts
      - Component.test.ts
      - ...
   - Component.hooks.ts
   - Component.strings.ts
   - Component.tsx
   - Component.types.ts

Screen Folder

The screen should follow this convention.

/Screen
    /components
   - `__tests__`
      - Screen.spec.ts
      - Screen.test.ts
      - ...
   - Screen.hooks.ts
   - Screen.styles.ts
   - Screen.tsx
   - Screen.types.ts

If the screen has components that are not used anywhere else, they should live in its folder. But always try to avoid this as we are pushing for an atomic design.


Documents

As a default, documentation should be written on /docs. With that, we can create our design documents and other related documentation, having them available for everyone that has access to the repository.


Spikes

Spikes are initial implementations of features to determine risks and assess how to the actual implementation will be tackled.

Spikes must be placed inside the /spikes folder. Every spike must have its own folder with a README.md file composed of the following sections:

  • Overview: Purpose of the spike.
  • {Tool/Library/Framework}: Replace this title by the name of the tool/library/framework being tested and complete with information and links.
  • Running the spike
    • Prerequisites: List of necessary tools to run the spike.
    • Steps: Step-by-step guide on how to run the spike.
  • Conclusion: Conclusion on whether its convenient to implement the tool within the system or not.

Atomic Design

Atomic design, developed by Brad Frost and Dave Olsen, is a methodology for crafting design systems with five fundamental building blocks, which, when combined, promote consistency, modularity, and scalability. In this project we only use 3 at the moment.

Atoms

Atoms are the smallest possible components, such as buttons, labels, inputs, animations, and fonts. They can be applied on any context, globally or within other components.

Molecules

They are the composition of one or more components of atoms. Here we begin to compose complex components and reuse some of those components. Molecules can have their own properties and create functionalities by using atoms, which may not have any function or action by themselves.

Organisms

Organisms are the combination of molecules that work together or even with atoms that compose more elaborate interfaces. At this level, the components begin to have the final shape, but they are still ensured to be independent, portable and reusable enough to be reusable in any content.



Version Control

##Branch Names

The branch name must have the following structure:

{TYPE}/{feature-description}

The TYPE can be one of:

  • build "Build system", new build of the system
  • chore "Chore", update of grunt tasks, etc.; no prod code changes
  • devops "DevOps", changes to devops related tasks
  • docs "Documentation", changes to documentation
  • feat "Features", new features
  • fix "Bug fixes", new bug fixes
  • perf "Performance", changes to improve performance
  • refactor "Refactor", refactor of production code
  • style "Style", formatting, etc.; no prod code changes
  • spike "Spike", code for analysis risks or sandbox implementations
  • test "Testing", add missing tests or refactor; no prod code changes

Examples:

  • docs/parsing-functions
  • feat/new-amazing-feature
  • fix/ui-flickering-bug

Branches Lifetime

Every branch that has already been integrated into the source branch, must be deleted both locally and remotely, to avoid branch cluttering.


Integration

When integrating changes from one branch into another, always use rebase instead of merge. The purpose is to keep a linear (and clearer) commit history.


Commits

Commits should be small and atomic. For more information about commits best practices, please head to this page.


Commit Messages

Commit messages should comply with the following rules, based on the conventional commits convention:

  1. Message length must have no more than 100 characters
  2. Commit title must be lowercase
  3. Commit title must not end with a period
  4. Commit title must have the following structure: type(optional-scope): description

Scope

The scope identifies the EPIC user story to which the change introduced in the commit is associated. In short, the overall topic of the feature it is modifying.

This element is optional in the commit title, but recommended.

Type

The type identifies the type of change introduced in the commit, and it can be any of the ones specified for branches.

Examples

Below you can find some examples of correct commit messages:

git commit -m "docs: add contributing guidelines document"
git commit -m "fix(endpoints): validation issue on users endpoint"
git commit -m "style(login): update login view to apply styling"