Skip to content

Latest commit

 

History

History
217 lines (154 loc) · 15.2 KB

CONTRIBUTING.md

File metadata and controls

217 lines (154 loc) · 15.2 KB
Raw

🛰️ contributing guidelines

🚧 prerequisite knowledge

🎩 style guide

a style guide for files and code has not yet been defined

however, the following resources provide a basis

the main goal is always to make the project look and feel like it was created and maintained by a single person

🏗️ setting up git and github

  1. first you'll need to download, install, and set up git on your local working machine
    • you should set your user.name and user.email
    • make sure to configure how your local system should handle line endings - for this project, set core.autocrlf to input on macOS and Linux or true on Windows
  2. after that, a github account is needed to contribute to this project (skip this step if you're already familiar with github)
  3. now you're all set to make small and simple changes to files in this project using the github ui

🚦 getting ready to work on the project

for more complex changes and tasks, you'll have to use git, a client like github desktop, or the github cli

the following steps use git on the command-line, but if you're already familiar with one of the options mentioned above, feel free to use the one you prefer

  1. create a fork of the project repository ("copy" the project on github)

  2. clone the forked repository from the first step to your local machine ("download" the copied project from github)

    # navigate to a directory of your choice
cd ~/web-dev/repos

# clone your fork of the repository
git clone https://github.com/YOUR-USERNAME/YOUR-FORK.git

# your local clone will be created
> Cloning into 'first-site-upgrade'...

  3. create a remote to be able to keep your fork up-to-date (create a "shortcut" to the original repository)

    # make sure to start in your clone directory
cd ~/web-dev/repos/first-site-upgrade

# add a remote repository called upstream
git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git

# verify the new upstream remote you have specified
git remote -v

> origin    https://github.com/YOUR-USERNAME/YOUR-FORK.git (fetch)
> origin    https://github.com/YOUR-USERNAME/YOUR-FORK.git (push)
> upstream  https://github.com/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git (fetch)
> upstream  https://github.com/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git (push)

# when a repository is cloned, git automatically adds a remote called origin
# origin points to your fork (the "parent" repository)
# upstream points to the original repository of the project

  4. open the project folder (clone directory) in your code editor (vs code for this project)

  5. vs code will prompt you to install the recommended extensions for the project (if not, search for @recommended in the extensions marketplace and install them manually); these extensions are mandatory for changes in this project

    • editorconfig support to override user/workspace settings with settings found in .editorconfig files
    • prettier code formatter to format files consistently
    • live-server hosts a local server in the workspace to preview web pages with features that depend on specific server technology, such as fetching data from files

👷‍♀️ working on the project

  1. sync your fork often to keep it up-to-date with the upstream repository to avoid conflicts or be able to resolve them

    # make sure to start in your clone directory
cd ~/web-dev/repos/first-site-upgrade

# checkout your local clone's default branch ("main" for this project)
git checkout main

# fetch the branches and their respective commits from the upstream repository
git fetch upstream

# merge the changes from the upstream default branch (upstream/main) into your local default branch (origin/main)
# this brings your fork's default branch into sync with the upstream repository, without losing your local changes
git merge upstream/main

# syncing your fork only updates your local clone of the repository
# to update your fork on github, you must push your changes (see next steps)

    you can update your current local working branch with git pull if you haven't made any local changes yet (local changes will be "overwritten")

    # make sure to start in your clone directory
cd ~/web-dev/repos/first-site-upgrade

# checkout your local clone's default branch ("main" for this project)
git checkout main

# update your local working branch with commits from the remote and update all remote tracking branches
git pull

  2. create a branch for your changes and "switch" to it

    # make sure to start in your clone directory
cd ~/web-dev/repos/first-site-upgrade

# checkout your local clone's default branch ("main" for this project)
git checkout main

# create a new branch with a summarizing name of the changes
git checkout -b YOUR-UPGRADE

# the command above switches to the specified branch and updates the working directory
# (it's a "shortcut" for "git branch YOUR-UPGRADE" and "git checkout YOUR-UPGRADE")

  3. now the actual work can begin: making changes, improvements, fixes, completing assigned tasks, or implementing requested features

  4. before moving on to the next step, review the checklist below

  5. after completing the work and checking the checklist, you'll have to add, commit, and push your changes

    # check that you're on the correct branch
# if you're not, use "git checkout YOUR-UPGRADE"

# add all new or changed files in your working directory to the git staging area (for the commit)
git add .

# make a commit with a short message describing the changes
git commit -m "your upgrades fixing an issue"

# push the commit(s) to the remote branch of your fork
git push
# use "git push --set-upstream origin YOUR-UPGRADE" if you haven't pushed this branch before
# or use "git push origin YOUR-UPGRADE" each time

    when in doubt, you can check the status of your working directory and staging area with git status

  6. once your changes are pushed to a branch on your fork, you can propose them with a pull request using the github ui - the pull request should have a clear title that summarizes the changes and a detailed description that explains them well

  7. the pull request will be reviewed, and feedback will be provided

    • it's a common part of the process in open source projects that you may be asked questions or asked to make adjustments to the changes
    • resolve conflicts if your pull request has merge conflicts with the main branch
    • group logical changes in each pull request so that it contains a related set of changes or just a single change

  8. finally, when everything is well-discussed, correct, and ready to be implemented, the pull request will be merged by a reviewer of the repository (the branch will usually no longer be needed and should be deleted afterward)

🦺 checklist

before releasing the changes, it's required to check the following items

⚙️ general

</> html related changes

  • validate the final html code with the html validator and resolve warnings and errors if necessary
  • test the fallbacks for the <video> and <audio> by temporarily renaming the tags (e.g., <novideo> or <noaudio>)

{} css related changes

  • validate the final css code with the css validator and resolve warnings and errors if necessary
  • check if used css properties are supported on can i use1
  • make sure to prefix css properties using the css autoprefixer tool1 if necessary

}); js related changes

  • check the console for warnings and errors, and resolve them if necessary

Footnotes

  1. browserslist: defaults, > 0.3% (global audience coverage: >90%) ↩ ↩2