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
orC:\Users\YourName\projects
on Windows, or/Users/YourName/projects
on MacOS.
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.
- Open the task on the MA platform
- Fork the repo
- Check your forked repo URL
- Clone the forked repo
- Open the project in IDE
- Open the Terminal in your IDE
- Run
npm i
- Run
npm start
to open the page in a browser - Open another terminal
- Create the
develop
branch - Update DEMO and TEST REPORT links
- Implement the task
- Run
npm run lint
to check the code style - Run
npm t
to pass tests - Run
git add ./src
to prepare your code for saving - Run
git commit -m 'add solution'
to save changes - Run
git push origin develop
to send your code to GitHub - Run
npm run deploy
to publish your site to GitHub Pages - Create a Pull Request (PR) with a correct description
- If you need to update your PR
Click the Make a fork
button. It will open the task repo on GitHub.
After the Fork process is finished, you should see the repo in your account (not the mate-academy
).
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.
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 theprojects
folder.- If not, navigate to it using the
cd
command with the required path.
- If not, navigate to it using the
- 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
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.
- Use the shortcut
ctrl + `
(Windows) orcmd + `
(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
And wait until it downloads all the packages and finishes.
Note: You should run it once for every new task.
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 thesrc/index.html
file. - The text should appear in the browser.
If the page is still empty after you added some text
If the page is opened at a different port (not :8080)
- If you see a different 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 pressingctrl + 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.
Use +
or just press ctrl + shift + `
or cmd + shift + `
.
Run:
git checkout -b develop
or
git switch -c develop
If you see that the "develop" branch already exists
- Open the
readme.md
file. - Replace the text
<your_account>
with your GitHub username in theDEMO LINK
andTEST REPORT LINK
.
You should write the code in index.html
and other files inside the src
folder.
Run:
npm run lint
This error means you need to fix CRLF
- Run
git config --global core.autocrlf false
. - Then, fix the CRLF in all the files you changed.
How to fix autoformatting in VSCode
- Here is the documentation.
- Run
Alt + Shift + F
to format the document.
- 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
).
Fix your HTML and CSS to make your page identical to the expected result.
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.
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
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.
Run:
git push origin develop
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 thereadme.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.
- If not, run
- Wait for about 2 minutes and reload the
Settings > Pages
again to see the link; - Open it to see your page.
- Select the
Pull Requests
tab; - Click the
New pull request
green button; - Change the
compare
branch on the right todevelop
; - Click the
Create pull request
button; - Copy the
DEMO LINK
andTEST REPORT LINK
fromreadme.md
to the PR description;- Links should contain your GitHub name (not
mate-academy
)!!!
- Links should contain your GitHub name (not
- Click the
Create pull request
button one more time; - Check that your
DEMO LINK
andTEST REPORT LINK
work as expected (open the page and test results); - Check if the task appeared in the table (only for full-time students).
❗ 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.
If you need an ADDITIONAL CODE REVIEW, click on the re-request button on the PR page.
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 likepermission denied
after running commands in the terminal.
The provided text seems mostly correct, but I've made a few adjustments to fix some minor typos and improve clarity:
npm install
installs the project dependencies and runspostinstall
- This creates reference files for pixel-perfect and tests
npm start
runs the server required for development and testsnpm test
runs the linter and testsnpm 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 togh-pages