Skip to content

Latest commit

 

History

History
312 lines (216 loc) · 15.7 KB

GUIDELINES.md

File metadata and controls

312 lines (216 loc) · 15.7 KB
Raw

IT-Challenge Style Guide

Table of Contents

  1. PROJECT'S LINKS
    1.1 Project's Links

  2. WORK PROCEDURES
    2.1 First things to do in the project
    2.2 Git configurations
    2.3 Daily Procedure
    2.4 Work with cards Procedure
    2.4.1 Assigning yourself a task-card
    2.4.2 Working on a task
    2.4.3 Pull request
    2.5 Working with git
    2.6 Scrum metodology

  3. CODING GUIDELINES

  4. STACK
    4.1 Framework
    4.2 Libraries

  5. REQUISITES

  6. INSTALLATION

  7. DEVELOPMENT

  8. TESTING

  9. DEPLOY

1. PROJECT'S LINKS

1.1 Project links

2. WORK PROCEDURES

2.1 First things to do in the project

0. Ask permission to collaborate with the project

1. Add your name to the file contributors.md

  1. Clone the Github repository ita-challenges-frontend in your local system:

      git clone https://github.com/IT-Academy-BCN/ita-challenges-frontend.git

  2. Move to the directory of the cloned repository:

      cd ita-challenges-frontend

  3. You can verify the available branches and your current branch by running the following command:

      git branch

  4. If you are not on the "develop" branch, switch to it by executing the following command::

      git switch develop

  5. Create a new branch with your name to make your changes:

      git switch -c your-branch-name

    Replace "your-branch-name" with a descriptive name that indicates the changes you plan to make.

  6. Open the contributors.md file and add your name and GitHub username.

  7. After doing a 'git add' and 'git commit', perform the following 'git push':

      git push origin your-branch-name

  8. Open the repository on GitHub. You should see a message that allows you to create a pull request from your newly created branch to the "develop" branch. Click on the link to create the pull request.

2.2 Git configurations

Necessary Git configurations to prevent problems

2.2.1 Git ignore

  1. Edit the .gitignore file: If necessary, you can now edit the ".gitignore" file to include any specific file or directory patterns that you want Git to ignore across all your projects. Remember to save the file after making any changes.

  2. Propagate changes: Changes in your .gitignore file will not retroactively affect files that have already been tracked by Git. If you want Git to start ignoring a file that was previously tracked, you must first untrack this file. Use the command 'git rm --cached filename' to untrack a file. For the changes to take effect, you'll need to commit this change.

  3. Avoid sensitive data: A good practice is to include files containing sensitive data (like configuration files with passwords or API keys) in your .gitignore file. This will prevent such files from being accidentally committed to your repository.

  4. Global vs local .gitignore: Remember, the global ".gitignore" file will apply to all your Git projects. If you have files to be ignored that are specific to a single project, consider using a local ".gitignore" file within that project's directory.

2.2.2 Autocrlf

Before all, please check https://docs.github.com/es/get-started/getting-started-with-git/configuring-git-to-handle-line-endings

Keep in mind that default encoding in project is UTF-8. Ensure that your text editor is set to uses that encoding.

2.2.3 File Mode

To avoid problems with file permissions, it is recommended to set the filemode configuration to false. This will prevent Git from tracking changes to file permissions. Execute globally

    git config --global core.filemode false

or locally

    git config core.filemode false

2.3 Daily Procedure

  1. Connect to Teams at 9:15 AM: Discuss difficulties and blockers.

  2. Switch to the 'develop' branch (git switch develop) and perform a 'git pull'.

  3. Switch to your working branch (git switch your-branch-name) and merge with 'develop':

     git merge develop

  4. Coffee break at around 10:30 AM aprox.

  5. At least once a day, execute 'git push origin your-branch-name'. Remember, you can set a default upstream branch in your local repository to easily push changes with 'git push':

     git push --set-upstream origin your-branch-name

IMPORTANT: It is expected that everyone on the project is online with their cameras turned on from 9:15 AM to 1:15 PM to work as a team (unless there are justifiable circumstances).

2.4 Work with cards Procedure

2.4.1 Assigning yourself a task-card

  • The project has been planned in several stages called "Epic".

  • Each Epic is further divided into "tasks", which are generally created by the technical lead.

  • Tasks are classified by their complexity by levels (1, 2, 3) from less to more complex.

  • To organize the task distribution, this dashboard with four columns is used:

    • ToDo: includes tasks that have not yet been started. All tasks (cards) start here.
    • Doing: tasks that are in progress.
    • Testing: tasks that have been completed and need to be reviewed by the mentor.
    • Done: tasks that have been reviewed, approved, and merged into the develop branch by the mentor.

  • Each participant needs to assign themselves a task card (by clicking on the card title > Add assignee > clicking the user's name) that is not assigned to anyone and move it to the "Doing" column (by dragging and dropping). In exceptional cases, the participant can create a task (below the columns, "+Add Item"); they should then provide a title and, optionally but recommended, a description and labels.

  • The tasks on the dashboard are actually "Issues" on Github. Therefore, these Issues can have labels (such as "Epic3", "Design", "Testing") that help provide an idea of the task's content.

2.4.2 Working on a task

-Once you have a task assigned, you will need to create a new branch dedicated exclusively to that task. The branch name format should always be "feature/#X", where "X" is the task number (which can be found at the end of the task title). For example, if your task is number 101, you would create a branch named "feature/#101".

The typical flow is as follows:

  • Create a branch, make changes and commit:

      git switch -c branchName (e.g., git switch -c feature/#101)
  git add .
  git commit -m "Commit message"

  • As mentioned, the first time you push your branch to the remote repository you can set an upstream branch:

      git push --set-upstream origin branchName

  • And then, everytime you need to push changes to the remote repository:

      git push

  • (Alternatively, you can omit --set-upstream and always simply use "git push origin branchName".)

There isn't a set way to do commits. You can follow the style of "conventional commits" (there is an extension in VSCode that can assist you with them): Conventional Commits. In any case, it is important that your commits are descriptive, clearly indicating where the change was made and what it consists of.

2.4.3 Pull requests

  1. Once you have finished working on your feature branch, you are almost ready to make the Pull request (PR). Before doing so, pull the last changes of the remote develop branch and merge them into your feature branch (see 2.3 Daily Procedure)

  2. Make sure to run the tests: "npm test" (also, you can run "npm test:watch" whenever you start working on the code to quickly catch any issues).

  3. Push the branch to the remote and ensure that automatic tests (like SonarCloud) pass: you will be notified of the results of the tests right after pushing. If your PR doesn't pass the test, review the log messages to find and solve the problems before you try a new PR. In that case, remember to pull and push again.

  4. Create a PR: Go to GitHub, and usually, if you have recently pushed changes, you will see a message like "There are recent changes in the feature-/#X branch, create a PR." If not, go to "Pull requests" > "New pull request" and select "develop > your-branch" > "Create pull request". Add a clear and concise description of the changes you have made.

  5. After doing the PR, you will see red-highlighted messages indicating that the merge cannot be done until someone approves the PR. This is normal, as the mentor needs to review and approve it.

  6. Once the PR is created, go to the bottom right and click on "Develop" to link the PR to the corresponding Issue (task).

  7. Go to the dashboard with the four columns. You will see that the task card you just completed has a reference to the corresponding PR. Move the card to the "Testing" column.

IMPORTANT NOTE: A pull request is a request to include your code into the project. Don't wait for your PR to be accepted to start working on another card.

2.5 Working with git

The workflow we follow is similar to the Gitflow Workflow. To work at the project, you should know at least following git commands:

  • git clone
  • git merge
  • git push
  • git pull
  • git branch
  • git checkout

A good tutorial is located at https://www.atlassian.com/git, and many other resources are available on https://docs.github.com/en/get-started/using-github/github-flow

2.6 Scrum metodology

https://scrumguides.org/ -Daily online meetings to discuss difficulties -Biweekly in-person meeting (Thursday) -Ocasional reviews with the client -Work by Epics > Tasks (Sprints)

3. CODING GUIDELINES

  • Clean Code
  • SOLID principles
  • Angular Styleguide. Main points:
    1. Use a feature-based folder structure instead of a type-based structure. -Group related files (components, services, etc.) in the same folder. -Use consistent and descriptive naming conventions for files and folders, such as kebab-case for folder names and PascalCase for class names.
    2. Class Naming: -Use PascalCase for class names, including components, directives, services, etc. -Append the "Component" suffix to component names. -Append the "Service" suffix to service names.
    3. Property and Method Naming: -Use camelCase for property and method names. -Avoid using "get" or "set" prefixes for property accessors.
    4. Template Conventions: -Prefix custom attribute names with "ng". -Prefix custom component selectors with "app".
    5. Code Organization: -Keep code concise and readable. -Group imports into separate blocks. -Sort imports alphabetically.
    6. Styles Handling: -Use Angular's component architecture to apply specific styles to each component. -Use SCSS classes for reusable styles and avoid inline styles.
    7. Subscription Management: -Unsubscribe from observables in components to prevent memory leaks and unnecessary resource usage. -Use takeUntil, unsubscribe operators or DestroyRef to manage subscriptions.
    8. Form Handling: -Use the ReactiveFormsModule module for form management. -Avoid using ngModel directives in complex forms.
    9. DOM manipulation: -Avoid directly manipulating the DOM, use data-binding, Angular built-in directives, ViewChild/ren... -For low-level DOM manipulation, use Renderer2
  • Languages: use only English for the code (you can use other languages for comments)

4. STACK

4.1 Framework

Angular 16.0.1

4.2 Libraries

Try not to overload the project with libraries.

  • Bootstrap: 5.2
  • ngBootstrap: 15.0.0
  • "jasmine-marbles": "^0.9.2",
  • Jest: "jest-jasmine2": "^29.5.0", "jest-preset-angular": "^13.1.1"
  • JWT:

5. REQUISITES

  • Node.js: Make sure you have Node.js installed on your system. You can download it from the official Node.js website.
  • Git bash: you will need it to contribute to the project.

6. INSTALLATION

  1. Open a terminal or command prompt.

  2. Navigate to the root directory of the project.

  3. Run the command

     npm install

    (or 'npm i') to install all the project dependencies specified in the package.json file.

7. DEVELOPMENT

For development purposes, use the command

    ng serve

to start the development server. This will compile the project and serve it locally, enabling you to view and interact with it in your browser.

8. TESTING

To run the tests, use the command

npm test

This will execute the test suite and provide feedback on the test results. If you prefer to run the tests in watch mode, which automatically re-runs the tests whenever a file changes, use the command

npm run test:watch.

If you need any reference about testing in Angular, you can check https://angular.io/guide/testing.
Also is available a guide about testing at https://martinfowler.com/articles/practical-test-pyramid.html

9. DEPLOY

Project development is deployed on develop server through Continuous Integration, not manually. All features developed are deployed on the develop server for testing when are approved. When you finish a feature, follow next steps:

  • Make sure your feature branch is up to date with the develop branch.
  • Make sure the name of your feature branch is right (feature/#X).
  • Follow semantic versioning (https://semver.org/), and update version number in package.json.
  • Update version number (property MICROSERVICE_VERSION) at file .env.CI.dev and package.json as well. Make sure both versions are the same. There should be a white line at the end of the file.
  • Make necesary annotations at file CHANGELOG.md
  • Push your changes to the remote repository.
  • Create a pull request from your feature branch to the develop branch.