Skip to content

Latest commit

 

History

History
246 lines (186 loc) · 13.5 KB

CONTRIBUTING.md

File metadata and controls

246 lines (186 loc) · 13.5 KB
Raw

Contributing Guidelines

This documentation contains a set of guidelines to help you during the contribution process.

We are happy to welcome contributions from anyone willing to add to or improve this project. Thank you for helping out and remember, no contribution is too small.

  • Each contributor can be assigned 2 issues (max) at a time to work on.

  • Contributors are expected to follow Project Structure Guidelines and Style Guidelines. Well written easy to read code is one of our top priorities.

    • walking-pal-web is a Next.js project.
    • We strictly abide by our Style Guide to style the React components.
    • We have an opinionated Project file structure, always follow our Project Structure Guide when creating new files/folders.

  • Contributors must comment on an open Issue that they would like to work on, and wait to be assigned by a maintainer.

  • Issues will be assigned on a first-come, first-serve basis.

  • Contributors may also open their own issues and assign themselves if they want to work on them. Before opening your own issues, check if a similar issue is opened already or not.

  • Guidelines to create new Issues:

    • Your issue title must be in the form of ISSUE_TYPE: ISSUE_TITLE
      • ISSUE_TYPE can be feat (issues for new features), bug(for bug), docs (for docs), chore(for miscellaneous)
      • ISSUE_TITLE must be clear and concise.
    • Make sure to give sufficient context in your issue description.
    • Wherever applicable, add reference links or screenshots.
    • If you are going to work on it yourself, mention that in the issue. You will be assigned by a maintainer.

  • Before opening a new issue, please check that it hasn't already been created.

  • Pull requests will be merged after being reviewed by a maintainer.

  • Create a pull request from a new branch other than dev.

  • Create a new branch from a freshly updated dev branch only. Do NOT create new branches from the main branch.

  • It might take a day to review your pull request. Please have patience and be nice.

  • We all are here to learn. You are allowed to make mistakes. That's how you learn, right!

  • MAKE SURE TO OPEN A DRAFT PR AS SOON AS YOU START WORKING ON AN ISSUE AND KEEP COMMITTING TO IT SO THAT WE CAN KNOW THAT YOU ARE WORKING ON THAT PARTICULAR ISSUE (see Converting Existing PR to Draft PR)

  • Contributors have 5 days to complete issues. If you think you will need more time, make sure to update your Draft Pull Request regularly by committing any changes you have made so far. This will help maintainers track your progress and assist you with your PRs more effectively. We want you to succeed in merging your PRs. We want to make sure that you learn open source in an effective way.

  • Pull request review criteria:

    • Your PR title must be in the form of PR_TYPE: PR_TITLE
      • eg, feat: new funky section, fix: fix the fencepost error, docs: add link to discord, style: make header component responsive, chore: add walkingpal logo
      • Refer Git Commit Guidelines for more details
    • Make sure you have created an issue for your PR. Link that issue to your PR.
    • Mention your proposed changes in the PR description along with screenshots and reference links (if applicable).
    • If you created new files, make sure they follow Project Structure Guidelines.
    • Your work must be original, written by you, not copied from other resources. Copying is not bad. But copying without properly understanding which parts of the code are needed and which are not is very bad. Make sure you avoid adding redundant code.
    • You must comment on your code wherever necessary. Avoid committing commented code, e.g console.log statements, etc.
    • For frontend changes kindly share screenshots and samples of your work before sending a PR.
    • For frontend changes, abide by the STYLE GUIDE.
    • ⚠IMPORTANT⚠ After creating your PR, Vercel will try to automatically deploy your PR code. If your Vercel build fails in your PR, you need to run yarn build locally and address those build errors. Your PR won't be reviewed until after the build errors have been fixed. It would be considered a WIP draft PR.

  • For any queries or discussions, see ASKING FOR HELP section.

Get started 👩‍💻👨‍💻

Development environment setup

Begin by following these steps to set up your development environment.

Install tools

The following tools should be installed and running on your computer:

  • GIT
  • Node.js (latest LTS version)
    • Install Yarn using npm install --global yarn

Setup Git

  1. Make sure that you personalize your GIT by setting your username and email for commits:

    git config --global user.name "John Doe"
git config --global user.email [email protected]

    ⚠️ Make sure to configure the same email as registered in your GitHub account. See here also

  2. Please refer to our Branching Strategy for more information about how we use branches and create releases. (TL;DR: When contributing a new feature or a bugfix, always create a new branch from the dev branch before you begin working.)

Get the Sources

  1. Fork the WalkingPal/walking-pal-web repository.
  2. Clone your forked <ur-github-username>/walking-pal-web repository 
    git clone https://github.com/<ur-github-username>/walking-pal-web.git
cd walking-pal-web
  3. Add our upstream WalkingPal/walking-pal-web repository with the label upstream 
    git remote add upstream https://github.com/WalkingPal/walking-pal-web.git
  4. Checkout to the dev branch and set up your local dev branch to track changes from upstream/dev 
    git checkout dev
git branch --set-upstream-to upstream/dev
  5. Install all project dependencies 
    yarn install

Additional Setup

#1 reCAPTCHA Setup

WalkingPal webapp utilizes reCAPTCHA to enhance security and prevent spammers/bots from polluting our database. To access the /register and /faq pages on the webapp seamlessly, follow the required steps:

  1. Head to the reCAPTCHA admin console and fill in the required details.

recaptcha-registration

  1. After clicking submit, you should be able to see the public and secret keys.

recaptcha-keys

  1. Create a file called .env.local and add the following to it. Then paste the keys you copied from the reCAPTCHA dashboard appropriately.
# Add the public site key here
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=
# Add the secret key here
RECAPTCHA_SECRET_KEY=

#2 Firebase Setup

We use firebase's for backend services. e.g We use firestore Database to store our forms data).

If you want to contribute on issues that need firebase services, follow these steps below to setup you new walking-pal-web firebase project

  1. Login to you google account and head on to console.firebase.google.com
  2. Click on Add Project Add Project
  3. Create a project (Step 1 of 3)
    • Enter project name: walking-pal-web. Click Continue
  4. Create a project (Step 2 of 3)
    • Click Continue
  5. Create a project (Step 3 of 3)
    • Click on Select an account => Click on Default Account on Firebase
    • Click Create Project
  6. After you come to Firebase "Console" Page, now its time to generate the Firebase Service Account key.
    • Click on "Gear Icon" on the left hand side panel.
    • Click on Project Settings
    • Click on Service Accounts
    • Click on Generate new private key
    • Finally, click on Generate key. This will download a JSON file. Save that JSON file. Do not share it with anyone. Firebase Service Account key generation step 1 Firestore Service Account key generation step 2
  7. Now we need to create a FIREBASE_SERVICE_ACCOUNT_KEY environment variable using that downloaded service account key JSON file. For that first we need to remove line breaks in the JSON file.
    • Go to textfixer.com and paste the content of the JSON file.
      • Do NOT remove the \n characters from the private_key fields or the key won't be valid afterwards.
    • Copy your newly generated text. That new text is without line breaks.
    • Create a .env.local file in the project root directory.
    • In the .env.local file, paste the copied text in FIREBASE_SERVICE_ACCOUNT_KEY key 
      # .env.local
FIREBASE_SERVICE_ACCOUNT_KEY='Put your copied JSON file content text without line breaks here'
# !IMPORTANT! You have to use single quotes (not double quotes)
      That's all! We have setup firebase with our NEXTjs project.
  8. Now let's setup Firestore too. On the left-hand side panel, click Build. Then click on Firestore Database. Firestore step 1
  9. Now Click on Create database Firestore step 2
  10. Click on Next Firestore step 3
  11. Then, Click on Enable. All done! We have Enabled Firestore database.
  12. [OPTIONAL] You can create a forms document in firestore.
    • In the forms doccument put 2 more documents namely early-users & feedbacks. After this, your forms on the website should work fine if you followed every step correctly.

Run Next.js development server

yarn dev

Open http://localhost:3000 with your browser to see the result.

You can start editing and modifying home page. The page auto-updates as you edit the file.

API routes can be accessed on http://localhost:3000/api/. This endpoint can be edited in pages/api/index.pg.ts.

The pages/api directory is mapped to /api/* route. Files in this directory are treated as API routes instead of React pages.

Learn more

To learn more about Next.js, take a look at the following resources:

Contributing Workflow

Find an issue 🔍

  • Take a look at the existing issues or create your own!
  • Wait for the issue to be assigned to you.
  • Note: Every change in this project must have an associated issue.
  • After being assigned, you can start working on your Pull Request.

Start working on your Pull Request

  1. Before you begin working on a new feature or bugfix, always first checkout the dev branch and update the dev branch

    git checkout dev
git pull #this command will pull changes from upstream/dev as we previously configured our dev branch to track from upstream/dev

  2. Create a new branch. We use Branching Strategy to create new branches. Example: Suppose you are going to start working on a bugfix that fixes a button's onClick behaviour. Create a branch name like: fix/button-onclick. Checkout the new branch and start working on your bugfix.

     git checkout -b fix/button-onclick
 # Now start working on your bugfix

  3. After finishing the bugfix, stage all your changes using the git add command.

  4. Commit all those changes with a nice commit message that follows our commit message guidelines.

    • If you get an error from husky commit-msg hook after running git commit command, this means that your commit message does not follow the commit guidelines. Correct your commit message.

  5. Push the changes to your forked repository

    git push origin <your-branch-name> #in our example the branch name is "fix/button-onclick"

  6. After pushing you will see a create pull request link as shown in the figure shown below: Creating A PR Create your Pull Request using that link 🎉

Converting existing PR to draft PR

If your Pull Request is a work in progress: go to your Pull Request and click on Convert to draft to convert it to a Draft PR. Converting Existing PR to Draft PR

Making changes to an existing PR

Sometimes maintainers may request changes in your PR. It is advised NOT to close the existing PR to create a new one. Instead, push changes to the existing PR branch. The PR will get automatically updated with your latest changes.

Asking for help

Join our discord server to meet WalkingPal's amazing community.

Make sure to read and follow the instructions in the #🚦start-here channel after joining the Discord server.

Ask your questions in the #💬devs-general channel.

That's all! Happy Contributing!!