Sisal NTB: Front-end Guidelines

Table of Contents

1. Introduction and Workspace Setup
2. General Rules
3. Folder Structure
4. Specific Guidelines
5. Ordering
6. Testing
7. Git

Introduction and Workspace Setup

Prerequisites:

• Node.js v10.13.0 min
• Yarn pkg manager v1.22.0 min
• Git scm v2.19.1 min

It's recommended the use of VSCode as IDE with these extensions:

• vscode-styled-components
• prettier
• git lens
• bracket pair colorizer
• auto rename tag
• auto close tag
• live share + live share audio
• todo tree
• error lens
• paste json as code
• visual studio intellicode
• beautify

Once cloned the repository:

cd inside the project folder run yarn command (only once) ​run yarn start command to start the local server

This project was bootstrapped with Create React App using the --template typescript option.

General Rules

This project mostly follows Airbnb React/JSX StyleGuides with some reservations.

• Write in TypeScript
• Absolutely avoid portions of code not covered by types:
  • as any is allowed only when typescript does not allow to express that type
• The components must all be functional:
  • except exclusively for 'errorBounbdaries'
• Use React.memo for components memoization:
  • memoized version of a components must have Memo suffix
• Styling components only through styled-components:
  • styled components must have Styled prefix
  • in-line style only through css={css``} formula
• For theming its used custom styled-theming
• Define props type at the top row of component definition
• Always declare types as type not interface
• Props type must have the same name as the component plus Props suffix
• To avoid prop drilling split up files in set of components only when they are:
  • independents from hooks
  • consistent

Linting

npm run start uses eslint with react-app preset

npm run lint uses eslint with airbnb-typescript preset

GOAL: fix airbnb-typescript configuration and add lint as precommit hook

• turn on quotes rule to ["warn", "double"]

Folder Strucure

• src is used as root folder
• First directory level by by domain (e.g., biglietto, smart-search)
• Prefer flat structure
• Second directory level by functionality (e.g. hooks, components) (but only if needed)
• Static assets directories (e.g. images, icons) in root folder (src)

Code locality first: write code near (in the same file) where is used, if code is reused move it upward to nearest common directory

Specific Guidelines

Variables

• Use const for all of your references; avoid using var.

  Why? This ensures that you can’t reassign your references, which can lead to bugs and difficult to comprehend code.

• If you must reassign references, use let instead of var.

  Why? let is block-scoped rather than function-scoped like var.

Naming Conventions

Name a file like React already does:

• Extensions: Use .tsx extension for React components.
• Filename: Use PascalCase for filenames. E.g., App.tsx, SmartSearch.tsx.
• Reference Naming: Use PascalCase for React components and camelCase for their instances.
• Use unique names for files (for better debugging and navigation experience)

// bad
import reservationCard from "./ReservationCard";

// good
import ReservationCard from "./ReservationCard";

// bad
const ReservationItem = <ReservationCard />;

// good
const reservationItem = <ReservationCard />;

Props

• Always use camelCase for prop names.

• Omit the value of the prop when it is explicitly true.

• Always include an alt prop on <img> tags. If the image is presentational, alt can be an empty string or the <img> must have role="presentation".

• Do not use words like "image", "photo", or "picture" in <img> alt props.

  Why? Screenreaders already announce img elements as images, so there is no need to include this information in the alt text.

• Avoid using an array index as key prop, prefer a stable ID.

  Why? Not using a stable ID is an anti-pattern because it can negatively impact performance and cause issues with component state.

• Always define explicit defaultProps for all non-required props.

Parentheses

• Wrap JSX tags in parentheses when they span more than one line.

Tags

• Always self-close tags that have no children.
• If your component has multi line properties, close its tag on a new line.

Mixins

• Do not use mixins.

  Why? Mixins introduce implicit dependencies, cause name clashes, and cause snowballing complexity. Most use cases for mixins can be accomplished in better ways via components, higher-order components, or utility modules.

Style

• Avoid creating a styled-component for every single HTML element in page:
  • Use in-line css in first instance
  • Write a styled-component if the element is repeated inside the component defined in that file
  • Abstract the styled-component inside its own file if the element in repeated across the project
• Use only the notation Muli or Roboto for font-family attribute
• Use the numeric notation for font-weight attribute (avoid use of bold, bolder etc.)
• Use rem as unit of measure for font-size. Default font size is 16px rely on this to make the conversions

Ordering

Top Down ordering approach inside a component

1. smart component (uses hooks)
2. hooks
3. data fetching
4. derived data (extract only if necessary)
5. dumb components (only graphical components with callbacks with few or no logic)
6. styled component

Testing

TODO

TBD

Git

Workflow

For this project we use GitFlow branching model.

New development (new features, non-emergency bug fixes) are built in feature branches.

Feature branches are branched off of the develop branch, and finished features and fixes are merged back into the develop branch when they’re ready for release.

When it is time to make a release, a release branch is created off of develop

The code in the release branch is deployed onto a suitable test environment, tested, and any problems are fixed directly in the release branch. This deploy -> test -> fix -> redeploy -> retest cycle continues until you’re happy that the release is good enough to release to customers.

When the release is finished, the release branch is merged into master and into develop too, to make sure that any changes made in the release branch aren’t accidentally lost by new development.

The master branch tracks released code only. The only commits to master are merges from release branches and hotfix branches.

Hotfix branches are used to create emergency fixes They are branched directly from a tagged release in the master branch, and when finished are merged back into both master and develop to make sure that the hotfix isn’t accidentally lost when the next regular release occurs.

Branch Naming

Branch name must begin with the user story or subtask id followed by the story/task name (all separated by dashes) eg.:

ntb98-inserimento-e-validazione

Crafting Commits

Commit is valid if...

• [ ] is consolidated or complete and "compile"

  • [ ] for incomplete changes you can (not mutually exclusive)

    1. use feature branches and maybe squash commits into one at the end during the rebase,
    2. use work-in-progress commits (and modify them with git commit --amend),
    3. commit but wait to push;

  • [ ] fot test commit (for example to force a CI) remeber that

    1. commits can be created without modification with git commit --allow-empty,
    2. if strictly necessary to do them on shared branches (master in primis) use a clear prefix such asWIP:at the beginning of the messages.

• [ ] is self-consistent: implements, corrects or removes a single specific functionality

  • [ ] if you are committing closely related features, use a single commit, but in the subject of the message make it clear that it is a substantial change and in the body of the message indicate all the new features inserted;
  • [ ] if you are committing features that depend on each other and it is not possible to make the change conservatively then use a single commit, but the message must indicate this aspect;

• [ ] is clean: includes only files and source changes related to the change

  • [ ] if you have modified other files not related to the specific task, do separate commits. Maybe let's get used to commit small changes immediately as soon as we are sure;
  • [ ] if in the same files you have different task modifications (for example you have formatted the source) attempt to commit separately - do not forget that all the UIs for git allow you to commit portions of modified files (also from the command line with git add --patch <file>);
  • [ ] if you have mistakenly added a file or a modification too much in a commit remember that you can modify it with git commit --amend, but only if you have not yet pushed.

General advice

• Whenever possible, avoid committing entire folders without reviewing what you are inserting - use the staging area as much as possible.
• If you use the command line learn to manually add one file at a time with git add <file> - it will help you design perfect commits.
• Before committing always check the changes you are adding: it is the opportunity to check if you are following the guidelines described above.
• Before pushing new commits always check the diffs that you have introduced: it is your last chance to review your commits!

Remember

• Time spent preparing a commit is always time well spent.
• A clean history is an indication of a team that works well.
• In a year, a well-written commit message can save several hours (if not days) of work.

Commit message is valid if...

• [ ] use the english language

  - Modificato stile delle dropdown
  + Change dropdown UI

• [ ] begins with a capital letter

  - change dropdown UI
  + Change dropdown UI

• [ ] is preceded by the work area

  - Environment variables
  - Add new utilities
  + Themes: Add new environment variables
  + SSO: Add new utilities
  + Chatbot: Implement auto-close functionality

• [ ] the first line (called subject) does not exceed 50 characters

  - Implement very cool new functionality that serves its pourpose, and that is to let custom dropdowns work
  + Implement custom dropdowns

• [ ] has an extended description separated by : and an empty line (and manually wrapped to 72 characters) when the 50 characters are too few

  + Themes: Fix custom dropdown behaviour:
  +
  + We previously used Liferay.Menu utility, but it since an unspecified
  + Fix Pack the ARIA support was dropped.
  +
  + With this commit we are changing the implementation to Bootstrap
  + jQuery plugins.

  (attention to : at the end of the first line!)

• [ ] describes the reasons of the change rather than the change itself

  - Chatbot: Fix update BotRule config
  + Chatbot: Fix location of BotRule config storage:
  +
  + When storing as file the configuration of a BotRule we need to use a
  + temporary folder in order for files to not show up on Documents and
  + Media apps.
  +
  + With this change we store them in a Portlet Repository.

• [ ] includes reference to any associated reports and description of the problem

  - SSO: Workaround for Liferay DXP bug
  + SSO: Workaround for BPER-13 (LPS-34567):
  +
  + We need to explicitly re-index the user after changes to the user’s
  + roles associations. This is a workaround.

• [ ] includes reference to any internal reports using the Fixes # NNNN pattern

  - Offices: Solve problems for 137
  + Offices: Let the user filter for office type:
  +
  + Fixes #137

• [ ] it is written in imperative form and can be inserted in this pattern:

  If applied, this commit will your subject line here

  - If applied, this commit will «cleanup»
  - If applied, this commit will «new files»
  + If applied, this commit will «clean theme files»
  + If applied, this commit will «remove useless files»
  + If applied, this commit will «implement something»

It is preferred to start the commit message with the user story or subtask id between square braces followed by colon and the subject eg.:

[NTB-98]: Change dropdown UI

Exceptions

Exceptions are some standard commit messages:

• SF, WS for commits that modify the source code white space and nothing else for reasons of source formatting
• SF for commits that modify the source code correcting possibly missing brackets and similar for reasons of source formatting
• Auto SF for committing the changes generated by the formatting tools: npm run format or yarn format;
• Initial commit and Initial import when the repository starts.
• Ignore <files> to identify the addition of <files> inside .gitignore
• Remove and ignore <files> to identify the addition of <files> inside .gitignore and their removal from the versioning system.

References

• How to Write a Git Commit Message https://chris.beams.io/posts/git-commit/