Skip to content

mate-academy/layout_task-guideline

BranchesTags

Repository files navigation

How to Solve the Layout Tasks on GitHub

This document explains everything you need to solve GitHub Layout tasks and send them for review.

  • ❗ To avoid permissions issues, DO NOT place your projects folder on the Desktop.
  • ❗ There should be NO SPACES in the path, e.g., C:\Users\Your Name\projects.
  • It is better to put repositories into D:\projects or C:\Users\YourName\projects on Windows, or /Users/YourName/projects on MacOS.

Before Implementing the First Task on GitHub

Connect GitHub to your Mate account.

  • Open your profile page on the MA Platform.
  • Scroll down and press the Connect button next to GitHub.
  • Confirm Mate Academy app authorization.

Follow These Instructions for All HTML/CSS Tasks on GitHub:

  1. Open the task on the MA platform
  2. Fork the repo
  3. Check your forked repo URL
  4. Clone the forked repo
  5. Open the project in IDE
  6. Open the Terminal in your IDE
  7. Run npm i
  8. Run npm start to open the page in a browser
  9. Open another terminal
  10. Create the develop branch
  11. Update DEMO and TEST REPORT links
  12. Implement the task
  13. Run npm run lint to check the code style
  14. Run npm t to pass tests
  15. Run git add ./src to prepare your code for saving
  16. Run git commit -m 'add solution' to save changes
  17. Run git push origin develop to send your code to GitHub
  18. Run npm run deploy to publish your site to GitHub Pages
  19. Create a Pull Request (PR) with a correct description
  20. If you need to update your PR

1. Open the Task on the MA Platform

Click the Make a fork button. It will open the task repo on GitHub.

2. Fork the Repo

Click the `Fork` button on GitHub

How to fork the repo

3. Check the URL of the Forked Repo

After the Fork process is finished, you should see the repo in your account (not the mate-academy). After the repo fork

Now you can check if it was synced to the MA platform.

  • Go back to the task on the MA platform.
  • The button should change to Open the task.
  • If not, reload the page.
  • Get back to the forked repo on GitHub.
If you need to delete a forked repo
  • Open project settings. Open project settings
  • Delete the repo. Delete the repo

4. Clone the Forked Repo

Now you need to clone the forked project to your computer. Follow the next steps (and see screenshots below):

  • Click the green Code button.
  • Select the HTTPS tab.
  • Ensure the link contains your GitHub name (NOT mate-academy).
  • Copy the link.
  • Open Git Bash (Windows) or ZSH (macOS) in your projects folder (You installed it in the Git and Terminal course).
  • Run pwd in the terminal to check that you are in the projects folder.
    • If not, navigate to it using the cd command with the required path.
  • Clone the repo by running the git clone command with the URL you copied on GitHub. 
    git clone replace-this-with-the-URL-from-github
How to open Git Bash

Git Bash here

How to paste the project URL to Terminal (Git Bash)

How to paste the URL into the terminal

Clone the repo Clone success

5. Open the Project in VSCode

Now you need to open the project in your code editor (VSCode).

  • Run code project-name in the terminal (for example, code layout_hello-world).
  • You will see the project name as a root folder name in VSCode.

The project opened correctly

Project is opened WRONG

The project opened correctly

6. Open the Terminal

  • Use the shortcut ctrl + ` (Windows) or cmd + ` (MacOS).
  • Check if you are inside the project (The project name is the last part in the terminal).
  • Check if the terminal in VSCode is Git Bash (Windows) or ZSH (macOS).
Click here to see how to select the default terminal in VSCode
  • Choose the Select default shell option. Select default shell
  • Select Git Bash (Windows) or zsh (macOS). Default shell popup
  • Close all the opened terminals.
  • All the new terminals will be Git Bash (or zsh).

7. npm install (or just npm i).

And wait until it downloads all the packages and finishes.

Note: You should run it once for every new task.

If you don't have Node.js

If you don't have Node.js

If you run `npm i` outside the project

If you run npm install outside the project

8. npm start to Open the Page

The command in the terminal will never finish.

  • The command should open your browser at http://localhost:8080/.
  • At this point, you should see the starting markup of the page.
  • If the page is empty, add some text to the <body> in the src/index.html file.
  • The text should appear in the browser.
If the page is still empty after you added some text
  • Update the page by pressing ctrl + r (cmd + r for macOS).
  • If the page is still empty, check if you saved the changes. Autosave is disabled
  • Enable autosave. Enable autosave
If the page is opened at a different port (not :8080)
  • If you see a different port. Wrong port
  • It means you already have another terminal running the npm start command (maybe it is another project).
  • Stop the npm start command in the current terminal by pressing ctrl + c (all operating systems).
  • Close the other terminal running npm start.
  • Run the command again for your current project.
  • The URL should now be http://localhost:8080/.
  • If the URL is still wrong, just restart the computer.

9. Open One More Terminal for the Next Steps.

Use + or just press ctrl + shift + ` or cmd + shift + ` .

Open one more terminal

10. Create the develop Branch

Run:

git checkout -b develop

or

git switch -c develop
If you see that the "develop" branch already exists

Develop already exists

  • Run git branch to see all existing branches. Show git branches
  • If develop is marked with *, then everything is correct.
  • Otherwise, run git checkout develop (without the -b key). Switch to develop

11. Update DEMO LINK and TEST REPORT LINK

  • Open the readme.md file.
  • Replace the text <your_account> with your GitHub username in the DEMO LINK and TEST REPORT LINK.

Update demo link

12. Implement the task described in the readme.md.

You should write the code in index.html and other files inside the src folder.

13. npm run lint to Check the Code Style

Run:

npm run lint
If you have some errors
  • Fix all the errors and run the command again.

Linter errors

How to find the lines with linter errors

The lines with errors

This error means you need to fix CRLF

CRLF linter error

  • Run git config --global core.autocrlf false.
  • Then, fix the CRLF in all the files you changed.

CRLF in current file

How to fix autoformatting in VSCode

HTML autoformat settings HTML autoformat json

14. npm test to Check if Solution is Correct

  • Read the checklist.md;
  • Fix your code if needed;
  • Run npm run lint again to ensure nothing is broken.
  • Run the tests: 
    npm test
  • Test results should be opened in a browser;
  • If not, check if you fixed all the code style errors (npm run lint).

If you see a failing test

Fix your HTML and CSS to make your page identical to the expected result.

Failed tests How to compare a test with reference

If you need to debug tests

If you can't run tests for some reason, just use a screenshot from backstop_data/bitmaps_reference/Entire_document.png to ensure your page looks as expected.

15. git add to Prepare Changed Files for Saving

git add ./src
  • Don't add irrelevant files at this point, like package-lock.json or test snapshots.
  • You can always check which files were changed or added using the git status command.
  • Also, don't forget to add the readme.md file.
git add readme.md

16. git commit to Save Changes

Run the commit with a message describing what this code does.

git commit -m 'add task solution'
fatal: unable to auto-detect email address
  • It means you forgot to configure your GIT name and email.
  • See the commands above the error message and run them one by one with your email and name.

If you forgot to set GIT name and email Set GIT name and email

no changes added to commit

No changes added to commit

LF will be

replaced with CRLF

  • You forgot to fix CRLF.

Forgot to fix CRLF

17. git push origin develop to send your code to GitHub

Run:

git push origin develop
failed to push some refs

Forgot to create develop Reset and create develop

  • Commit changes again after creating the develop branch.
If you are asked for Authorization

GitHub auth popup Authorize GIT credentials manager Push success

fatal: unable to access

Permission denied Add correct origin

18. npm run deploy to Publish to GitHub Pages.

Run:

npm run deploy

If you are getting some errors, run npm run deploy -- -l to see more details.

The deploy process requires some time to prepare your page on GitHub after the command is finished.

To check if the page was deployed successfully, you need to check in the project settings on GitHub:

  • Open the forked repo on GitHub;
  • Click the Settings tab at the top;
  • Choose the Pages section from the panel on the left;
  • There should be a link to your public page at the top (the same as your DEMO LINK in the readme.md).
  • If there is no link at the top, check if the gh-pages branch appeared in the repo;
    • If not, run npm run deploy -- -l to see more details.
  • Wait for about 2 minutes and reload the Settings > Pages again to see the link;
  • Open it to see your page.

19. Create a Pull Request (PR)

  • Select the Pull Requests tab;
  • Click the New pull request green button;
  • Change the compare branch on the right to develop;
  • Click the Create pull request button;
  • Copy the DEMO LINK and TEST REPORT LINK from readme.md to the PR description;
    • Links should contain your GitHub name (not mate-academy)!!!
  • Click the Create pull request button one more time;
  • Check that your DEMO LINK and TEST REPORT LINK work as expected (open the page and test results);
  • Check if the task appeared in the table (only for full-time students).

New pull request Create pull request Add DEMO Links

❗ Do NOT close the PR and ❗ do NOT open several PRs. Only the first PR made after the fork is synced to the platform.

  • If you have closed the PR - reopen it and request mentor review.
  • If you can't open the PR - do another fork and create a new PR.
Check your DEMO LINK
  • You forgot to put your GitHub name into DEMO_LINK and TEST_REPORT_LINK.

Forgot to fix DEMO LINK

Check your TEST REPORT LINK
  • You forgot to run tests before npm run deploy.

Forgot to run tests before deploy

20. To update your PR, repeat steps 13-18 (no need to create the PR one more time).

If you need an ADDITIONAL CODE REVIEW, click on the re-request button on the PR page. Image of re-request button

Linux Users

If you use Linux, please make sure you adjusted writing permissions to let scripts work without sudo. Correct permissions mean you don't see errors like permission denied after running commands in the terminal.

NPM Commands

  • npm install installs the project dependencies and runs postinstall
    • This creates reference files for pixel-perfect and tests
  • npm start runs the server required for development and tests
  • npm test runs the linter and tests
    • npm run lint runs the linter (code style check)
    • npm run test:only runs pixel-perfect tests
  • npm run deploy publishes the page and test report to gh-pages

Useful Links

About

No description, website, or topics provided.

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

1 star

Watchers

9 watching

Forks

123 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 18
+ 4 contributors