Skip to content

Latest commit

 

History

History
181 lines (127 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

181 lines (127 loc) · 10.3 KB

Contributing to git_basics

  • Please be mindful of the Code of Conduct while interacting or contributing!
  • First time contributors can solve good first issues.
  • Any contributor with some Git and GitHub knowledge can consider adding some of the requirements listed in the issues.
  • If any contributor wants to tackle an issue or a part of it, please leave a comment on the issue (mentioning the part they want to tackle), so that they can be assigned to that part of the issue and multiple people do not handle the same part of the issue.

Tech Stack

NOTE:

  • This project uses a Static Site Generator called Asciidoctor.
  • This project is a PWA and a TWA. (Asset links file)
  • GitHub Actions has been set up on this repo, so a built web site does not have to be committed.

Gitpod Setup

Open in Gitpod

  • On clicking on the above 'Open in Gitpod' button, a Gitpod Workspace with Asciidoctor and other dependencies installed will open up.
  • A GitHub integration will be required on Gitpod if not already done. Also, make sure to give appropriate permissions to GitHub on the Integrations page.
  • Please adhere to the file structure and language, code and syntax rules followed in this project.
  • Make a new Git branch on Gitpod and switch to the newly created branch.
  • For testing, generate the web site in a directory called build in the root directory by running the command sh build.sh from the root directory.
    • To host the site locally from the build directory, run the command serve build from the root directory.
      • One can also use the Live Server VS Code extension that should have been automatically been installed.
        • Click on the 'Go Live' button in the Status Bar at the bottom of the window.
    • Please do not commit this build directory, as the CI process will build the site on merge.
    • A browser window with the web app should automatically open up, but if it doesn't, ctrl + click the link in the terminal to open up a window.
    • NOTE: The summary will have to be built manually using the sh build.sh command every time there is a change. The browser will then have to be refreshed to view the change.
  • Make the required contribution(s) on Gitpod in the new branch.
  • To open a PR

Local Setup

  • Fork this repo. (Top right corner.)

  • Clone the forked repo using the git clone command.

  • Install Asciidoctor.

  • Please adhere to the file structure and language, code and syntax rules followed in this project.

  • Testing

    • Generate the web site in a directory called build in the root directory by running the command sh build.sh from the root directory.
      • It is preferable to use a package like http-server (npx http-server "build") or serve (npx serve "build") to host the site locally from the build directory.
      • Please do not commit this build directory, as the CI process will build the site on merge.

  • Make contribution(s)

    • Write meaningful commit messages and include the number (#) of the issue being resolved (if any) at the end of the commit message.

      Example: :bug: fix: Resolve 'isCorrect' function error (#0)

      Commit message format

  • Open a Pull Request (PR).

    • Learn how to open a PR.
    • Solve one issue per PR, without any extra changes.
    • Include extra changes in a separate PR.

File Structure

Parsing

Asciidoctor parses files starting from index.adoc and follows include:: to the relative location of the next file, to finally get to the file with the content.

Example:

This is how the content of git_add.adoc is displayed:

Check the raw file contents for the exact syntax.

Static Files

  • CSS, JS and images are located in the ./src/static directory. Add the appropriate static files to the appropriate static directory.

Caching

  • If any static file is added, please make sure to
    • Include it in the cacheAssets array in ./src/service_worker.js as a relative path.
    • Increment the value of the cacheName variable. (Example: From v2 to v3.)
    • Add it to ./src/docinfo.html with the correct syntax if the static file needs to be linked to the final site.
  • If any static file is modified, please make sure to
    • Increment the value of the cacheName variable. (Example: From v2 to v3.)
  • If any static file is deleted, please make sure to
    • Remove it from the cacheAssets array in ./src/service_worker.js.
    • Increment the value of the cacheName variable. (Example: From v2 to v3.)
    • Remove it from ./src/docinfo.html if present.
  • If any static file is renamed, please make sure to
    • Rename it in the cacheAssets array in ./src/service_worker.js.
    • Increment the value of the cacheName variable. (Example: From v2 to v3.)
    • Rename it in ./src/docinfo.html if present.
  • The cacheName should be updated just once per commit.

Images

Images should have

  • A solid colour background. (No transparent images.)
  • A width and height of 600px, unless that distorts the picture or makes it illegible, in which case suitable dimensions can be used.
  • An alt attribute describing the image in a few words.

Example:

image::file_name.ext[alt="image description", 600, 600, ...]

Language, Code and Syntax

  • Pronouns are either omitted (preferred) or third person pronouns ('they', 'their', 'one', etc.) are used.

    Example:

    • Code should be committed frequently. ✔️ (Preferred)
    • One should commit code frequently. ✔️ (Accepted)
    • You should commit code frequently. ❌ (Not accepted)

  • Prettier should be used to format code.

  • The AsciiDoc extension can be used, for syntax highlighting in .adoc files in VS Code.

  • Asciidoctor syntax (Quick reference.)

  • Use the same syntax as used in the other files to maintain uniformity. Avoid using variations in syntax.

  • Writing in bullet points is preferable.

  • Bold, underline and italics should be used sparingly.

  • Surround single line commands or file names with a single 'back tick' (`).

  • Surround code snippets with three 'back ticks' (```).

  • External links should include a caret (^) at the end of the link text to open them in a new tab.

    Example:

    • link:https://github.com[This is a link to another site^] (Caret at the end for external links.)
    • link:#_issues[This is a link to the same site] (No caret at the end for internal links.)

  • If external links are pasted as normal links, do following to open it in a new tab

    Example: link:https://github.com/HarshKapadia2/git_basics[github.com/HarshKapadia2/git_basics^]

  • Links should have meaningful text.

    Example:

    • It can be found in the link:https://docs.github.com[official documentation^]. ✔️ (Accepted)
    • It can be found link:https://docs.github.com[here^]. ❌ (Not accepted)

Further Help

If any further help is needed, do not hesitate to contact the owner (Harsh Kapadia) via OTC, Twitter, LinkedIn or e-mail ([email protected]). An issue can be raised as well.