Frontend 2021 course homeworks

This repo was created for students to submit their homeworks for review.

Please follow the instructions below to submit your code for review.

Table of Contents

• Overview of contribution flow
• Glossary
• Contribution stage A. Setup the fork and local clone
• Contribution stage B. Adding new code and updating submissions
  • B1. Submitting new task (app) code base
  • B2. When any changes are required
  • B3. When all of your PRs are finally merged
• Reference materials and troubleshooting

Overview of contribution flow

Now you are a contributor to an educational open source project.

These slides visualize the contribution workflow.

The instructions below will lead you through the contribution workflow as you will submit your tasks code base.

Glossary

Term	Definition
repo	short for 'repository'
homeworks main repo	Kottans FE course homeworks repository: https://github.com/kottans/frontend-2021-homeworks
homeworks fork	your own fork of homeworks main repo
homeworks local repo	your local clone of your homeworks fork
app	an application (or web page) you develop to fulfil a specific task in the course
app repo	a repository that contains your application code

Contribution stage A. Setup the fork and local clone

You need to do this only once.

A1. Fork homeworks main repo via GitHub web interface

A2. Clone homeworks fork on your local machine:

• git clone https://github.com/YOUR_USERNAME/frontend-2021-homeworks.git

Make sure you are inside the homeworks local repo directory before any further operations

A3. Add homeworks main repo as an upstream:

• git remote add upstream https://github.com/kottans/frontend-2021-homeworks.git

A4. In homeworks local repo, add a folder with your github username under submissions directory

You will add code from your every task (app) in its individual directory under your named directory. So, the file structure will be similar to the following (in this example amashoshyna is a username and js-dom is a task name)

Contribution stage B. Adding new code and updating submissions

B1. Submitting new task (app) code base

IMPORTANT things to remember at all times.

1. Do not commit to main.

2. checkout main before creating a new branch, i.e. do not create a new branch while on any branch that is not main.

3. Do not merge your branches into main. You can merge main into your branch if you realize why you need this. In current workflow you normally do not need this.

And don't panic if some code seems to be gone when you switch between branches. It will be available to you once you switch back to a specific branch. The point is to submit tasks in isolation from each other.

B11. Make sure that the app you develop to complete the task:

(a) has its own dedicated project/repository on GitHub (app repo)

(b) is published on GitHub pages

B12. In your homeworks local repo do the following:

B121. Sync up main branch of your homeworks local repo and homeworks fork (origin) with the main branch of homeworks main repo (upstream):

• git checkout main
• git pull upstream main
• git push origin main

At that moment you may already have some code under some other task branch and it may seem to be gone. Don't worry, it is still available under its own task branch. No need to merge that branch into the main, and do not merge it into the main as this will most likely entail code conflicts.

B122. Create a dedicated branch for your new task (app) code base while on the main:

• git checkout main
• git branch <task-branch-name> (<task-branch-name> can be e.g. dom-api-task)

B123. Add required files:

• git checkout <task-branch-name>
• create a directory for your task (app) code base under ./submissions/YOUR_USERNAME so that the path to your task is ./submissions/YOUR_USERNAME/TASK_NAME (see the screenshot above for an example of the structure you are expected to have)
• copy files from your app repo, those and only those that are required for the review

IMPORTANT! Put only files/code required to conduct review, i.e. html, css, js files and such. Images, icons, IDE directories like .idea, .vscode etc are not required for code review. Never have .git directory in your task submissions. Copy required files one by one. Never copy the directories in bulk as this may entail copying unwanted files and hidden directories.

• stage files with git add command and commit changes

B124. Open a Pull Request (PR):

• push to homeworks fork: git push --set-upstream origin <task-branch-name>
• wait until push operation completes successfully
• navigate to your homeworks fork on GitHub
• GitHub will offer to open a Pull Request from your new task branch; Just do it

• you will be offered a PR template message with instructions; read them and fulfil as prescribed
• once PR is open, check Files changed to see what's being submitted

Make sure your PR doesn't contain any unrelated files or commits from any other tasks, and no files from other your tasks or from other authors are being deleted

B125. Ask for a review:

• post a link to your PR in the FE Questionarium chat and ask mentors and peers for a code review
• monitor your pull request for possible change requests

B2. When any changes are required

Whenever you want or are requested to make any changes do the following:

B21. Update your app (in the relevant app repo):

• implement changes
• make sure your app publication is updated

B22. Update your submission PR - in your homeworks local repo:

• git checkout <task-branch-name>
• copy changed files (one by one) to your task directory from the app repo
• stage, commit and push

Your PR will be updated automagically.

B23. Check your PR and summon a mentor:

• navigate to your PR in homeworks main repo
• check your submitted files under Files changed; you will want to see your latest changes in the files
• click Re-request review icon in the list of your PR reviewers to draw mentors' attention, so that they know you changed your code and there is something new to see

When your submission gets finally merged, put your reflections on the task and your code review experience to your student's diary (your kottans-frontend repo):

• what was new to you
• what surprised you
• what you intend to use in future

B3. When all of your PRs are finally merged

Update homeworks local clone and your homeworks fork to have all of your code under the main branch:

• git checkout main
• git pull upstream main
• git push origin main

Reference materials and troubleshooting

1. Contribution guide for beginners.
2. Refer to this troubleshooting guide whenever you face any conflicts when updating main from the upstream (original repo) or have unrelated files or commits in your pull requests
3. Any issues? Ask community. Many others had similar issues, the community will help you out