Skip to content

Instantly share code, notes, and snippets.

@roalcantara

roalcantara/Guidelines.md

Created February 13, 2021 17:07
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save roalcantara/fbff4754bf50f637197b15ba774f9922 to your computer and use it in GitHub Desktop.
Save roalcantara/fbff4754bf50f637197b15ba774f9922 to your computer and use it in GitHub Desktop.
Download ZIP
Project Guidelines
Raw
Guidelines.md

Project Guidelines

semantic-release Conventional Commits code style: prettier

This project was generated with Angular CLI using Nrwl Nx.

Getting Started

Before start

Quick Start & Documentation

Watch a 5-minute video on how to get started with Nrwl Nx.

Generate your first application

When using Nx, you can create multiple applications and libraries in the same CLI workspace.

Development

Run ng s my-app for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Code scaffolding

Run ng g <schematic> <name> --project=<name> to generate and/or modify files based on a schematic.

Schematics

Some of the schematics available are:

Lint

Run ng lint my-app to lint the project.

  • Run nx affected:lint lint affected apps and libs.
  • Run yarn affected:lint:parallel to lint affected apps and libs, in parallel.

Build

Run ng build my-app to build the project. The build artifacts will be stored in the dist/ directory. Use the --prod flag for a production build.

  • Run nx affected:build to build affected apps and libs.
  • Run yarn affected:build:parallel to build affected apps and libs, in parallel.

Staging

  • Run yarn affected:build:stag to build affected apps and libs for staging.
  • Run yarn affected:build:stag:parallel to build affected apps and libs for staging, in parallel.

Production

  • Run yarn affected:build:prod to build affected apps and libs for production.
  • Run yarn affected:build:prod:parallel to build affected apps and libs for production, in parallel.

Tests

Unit Tests

  • Run ng test <lib|app> to execute the unit tests via Jest.
  • Run ng test <lib|app> -t=<regex> to execute only tests with a name that matches the regex.
  • Run ng test <lib|app> --test-file path/to/file.spec.ts to execute a single file.
  • Run ng test <lib|app> --verbose .. to display individual test results with the test suite hierarchy.
  • Run ng test <lib|app> --pass-with-no-tests .. that allows the test suite to pass when no files are found.

In case of no tests found, avoids failure in CI by setting the passWithNoTests variable at jest.config.js

  • Run nx affected:test to execute the unit tests affected by a change.
  • Run yarn affected:test:parallel to execute the unit tests affected by a change in parallel.
  • Run yarn affected:test:parallel to execute the unit tests affected by a change, in parallel.

IMPORTANT:

Ensure that your yarn global packages are in sync with the package.json:

End-to-end Tests

Run ng e2e my-app-e2e to execute the end-to-end tests via Cypress. Before running the tests make sure you are serving the app via ng serve.

Semantic Release

We use semantic-release to automate the whole package release workflow including:

  • Determining the next version number
  • Generating the release notes
  • Publishing the package

Run npx semantic-release --dry-run --no-ci --debug to skip publishing, print next version, release notes and debugging information.

Get to know more here.

Manual Release

Run yarn release, which will:

  • Fetch, prune and force checkout the develop branch
  • Force checkout the master branch
  • Fast-Forward merge the develop into the master branch
  • Load the GH_TOKEN from the local .env file
  • Run the semantic-release script
  • Merge the master into the develop branch
  • Push develop to remote

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.

Guidelines

1. Why a Monorepo

This is a monorepo project built with Nrwl Nx.

From the Nrwl Nx docs:

Developing Like Google, Facebook, and Microsoft

Working with multiple applications and libraries is difficult. From Google to Facebook, Uber, Twitter and more, a good amount of large software companies handle this challenge by taking a monorepo approach. And they have been doing so for years. These are some of the advantages this approach provides:

  • Everything at that current commit works together. Changes can be verified across all affected parts of the organization.
  • Easy to split code into composable modules
  • Easier dependency management
  • One toolchain setup
  • Code editors and IDEs are "workspace" aware
  • Consistent developer experience

To get to know more

2. Team Workflow

3. Coding Best Practices

4. Coding Style

Coding Style Tools

Code Style Changes

To propose a new rule or a code style change, please:

  1. Open a pull request
  2. On the PR title:
    1. A summary of the change
  3. On the PR description:
    1. Describe the problem you want to solve.
    2. Your take on the correct solution to the problem.
    3. Any relevant resource that would endorse such a change
  4. Add a commit providing 2-3 examples for the proposed solution
    1. Preferably on a real code
  5. Request the review for the change for teammates
  6. Being approved by 51% of the teammates:
    1. Configure the rule properly;
    2. Apply the rule on the whole codebase on the project;
    3. And the PR follows the regular Pull Request flow; YAY!

5. Testing

  • Write unit tests with Jest.
  • Write E2E tests with Cypress.
  • Apply the Better Specs best practices for testing - as much as possible.

6. Git Commit Guidelines

Commit Messages

Follow The seven rules of a great Git commit message (TL;DR)

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Commit Types

As configured on .commitlintrc.yml, it must be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • ref: A code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests or correcting existing tests
  • revert: A commit that reverts a previous commit
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
  • ci: Changes to our CI configuration files and scripts (example scopes: Circle, BrowserStack, SauceLabs)
  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • perf: A code change that improves performance
  • git: Changes on git files, such as .gitignore

Commit Best Practices

  • Commit often
  • Keep commits small and atomic
  • Write S.O.L.I.D. commits
  • Write meaningful titles targeting for non-technical readers
  • Write commits that would help the Code Review
  • Add any extra information that would help the Code Review
  • Reference the issue that originated the commit

7. Pull Requests

One would say that some of the main purposes of Pull Requests are:

  • Add a product increment
  • Remove obsolete code/behaviour
  • Fix a product problem
  • Enhance product behaviour
  • Refactor code to improve quality
  • Add/change some architecture requirement
  • Update libraries or improve security
  • Discuss the better approach to certain issues

Main Goals

The ideal PR must be:

  1. As smallest as possible
  2. Defects free
  3. Easy to be reviewed and validated
  4. Reviewed and validated as soon as possible
  5. Merged as soon as possible
  6. Have been approved by at least one reviewer

Best Practices (TL;DR)

  1. Prefer one feature/fix/refactoring per PR
  2. Estimate the PR before starting it
  3. Link the PR to an Issue before starting it
  4. Comment any consideration/doubt/problem/discussion/definition on the PR`s Issue;
  5. Try to have, at least, one Unit Tests per change, when applicable
  6. Try to make a PR that you would enjoy reviewing
  7. Remember, the next reviewer can be you

Before sending the PR to Code Review ensures that

  1. Any implementation follows the Coding Best Practices and any team Style Guide
  2. Any commit follows the Commit Best Practices
  3. Any change has been tested at least once. That is:
    1. Running the program
    2. Checking if the change works
  4. All project's Unit Tests are keeping running
  5. There are no linter violations on the project
  6. You have reviewed your own code

To Get Better Code Review ensures that

  1. The PR has:
    1. The minimum changes necessary to accomplish the PR`s goal
    2. The minimum commits necessary to accomplish the PR`s goal
    3. A clear, short and concise title that summarizes the changes
    4. A clear description that contextualizes the problem you’re solving
  2. Any relevant explanation or reference is present on the PR`s description or commits;
  3. Whenever necessary, the PR describes how it must be validated
    1. Adding any relevant info necessary to the validation, such as username, environment, password, deadline, and etc.
  4. Avoid refactorings not related to the PR's goal
    1. Because it might difficult the Code Review
    2. However, if the refactoring is inevitable
      1. It should be properly isolated and justified

8. Code Reviews

One would say that some of the main purposes of Code Reviews are:

  • Detecting and Reducing defects
  • Sharing knowledge on the architecture, business logic, design patterns, and techniques
  • Promoting the collective ownership of the code

Suggested Checklist

  1. Try to understand the change and its impact on the codebase and on the product
  2. For each change, ensures that
    1. It is clear
    2. It mets the requirements
    3. It has no defects
    4. It has, at least, one unit test
    5. It follows the Coding Best Practices
  3. For each commit, ensures that
    1. It follows the Commit Best Practices

Best Practices (TL;DR)

When reviewing a Pull Request, try to:

  1. Focus more on finding
    1. Defects
    2. Logic problems
    3. Performance issues
    4. Bugs
  2. Focus less on
    1. Changes that have not been made on the commit
    2. Things not related to the Pull Request goal
    3. Coding style
    4. Nitpicking
  3. Give, at least, one comment. When so, try to:
    1. Ask, don't tell
    2. Highlight wins
    3. Highlight things that you've learnt
    4. Articulate the problems (if any) and suggest alternatives
    5. Mind your language and tone
      1. It is incredibly easy to misunderstand something online
  4. Remember:
    1. It is perfectly possible to have more than one way of solving a problem
    2. Code Reviews are more efficient when focusing on defects rather than code style
    3. Code Styles should be ruled automatically by tools. That is:
      1. If a code has no error, performance issue, defect, nor violates any linter rule, it is probably ok
    4. Some ideas are better conveyed face-to-face
    5. You might have to maintain this change in the near future

Resources

Here are some highly recommended resources on the topic:

9. Contribute

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment