CONTRIBUTING.md

Welcome, Contributors! 😄

• Please check the issues tab for things to work on.
• Please raise an issue for adding a new feature or for reporting a bug, if it has not already been raised.

Tech Stack

• Front end: HTML, CSS, JS, Asciidoctor Jet
• Back end: Express.js, Deta Micro, Deta Base

Gitpod Setup

• On clicking on the above 'Open in Gitpod' button, a Gitpod Workspace with all dependencies installed will open up.
• Start the dev server by running npm run start in the root directory.
  • 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 server will have to be re-started manually to build the summary pages, as builds happen just once on starting the server.
• A GitHub integration will be required if not already done. Also, make sure to give appropriate permissions to GitHub on the Integrations page.
• To open a PR
  • Fork this repo. (Top right corner.)
  • On Gitpod, add the forked repo as a remote.
  • Make a new Git branch on Gitpod.
  • Make the required contribution(s) on Gitpod in the new branch.
    • Please follow the commit message format.
  • Push the new branch to the forked repo.
  • Open a PR as usual from the forked repo.

Local Setup

• Fork this repo. (Top right corner.)

• Clone the forked repo using the git clone command.

• cd into the cloned repo directory.

• Run npm install in the root directory of the project to install all dependencies.

• Install Asciidoctor.

• Create a .env file in the root directory of the project with the contents of the sample.env file. The sample.env file has placeholder_text as variable values to prevent errors.

• Run npm run start in the root directory of the project to build the summary site once and start a hot reload server. The web app should be accessible on http://localhost:<port>. (The port will appear in the server console.)

• The summary site uses a Static Site Generator called Asciidoctor.

  • Run the command sh util/build.sh in the root directory of the project to build the summary site.
  • The site should be accessible at http://localhost:<port>/summary or http://localhost:<port>/summary/<summary_number> after running npm run start in the root directory of the project. (The port will appear in the server console.)
    • The npm run start builds the summary site just once, so for further Asciidoctor changes to reflect, the command will have to be run again.

• 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 #2)

    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.

Further Help

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