Contribution Guide

Follow this step-by-step guide to contribute to CA Resources and help us enhance our community-driven project!

This guide assumes you have a GitHub account and are familiar with the basics of Git and GitHub.

Fork the Repository

Begin by visiting the project repository and clicking the Fork button. This action creates a personal copy of the repository under your account, allowing you to make changes without affecting the original project. For more details, refer to the GitHub Docs on Forking.

Clone Your Fork

Next, clone your forked repository to your local machine. This allows you to work on your contributions in your local development environment.

git clone https://github.com/your-username/ca-resources.git

Make sure to replace your-username with your actual GitHub username.

Create a New Branch

Before making any changes, create a new branch with a descriptive name that reflects the nature of your contribution. This helps keep your work organized and makes it easier for others to review.

git checkout -b v2/add-resource

File Path Where the Resources are Stored

The resources are stored in the resources.ts file located at:

resources.ts

page: { // object key as the resource path
  title: "",
  // ...
  resourcesList: [
    {
      title: "", // Title of the resources category (optional)
      links: [
        {
          title: "", // Title of the specific link
          url: "",
          description: "",
          iconPath: "",
        }
      ]
    }
  ]
}

Steps to Gather Resource Information

Use Desktop/Laptop

It is recommended to use a desktop or laptop for ease of gathering information by inspecting website elements. Open the website you want to add.

Gather Title

Using developer tools, inspect the website’s <title> element inside the <head> tag and copy the text to use as the resource title.

gather title

Get the URL

Copy the main website URL. If the webpage is a subpage, it's acceptable to use it as long as it directs users to the main webpage where the resource is located.

Get the Description

Look for the <meta name="description" content="..."> tag in the <head> section. Copy the content attribute's value as the description.

gather description

If it's not available, you can use AI to describe the website.

Find the Icon

Use favicon.ico if there are no icons available, but try to find a high-resolution icons first. If multiple icons are available, choose one that is similar to the favicon used. Some websites may not have an icon; you can leave it blank. Store icons in the relevant folder inside /public/resources/.

Example Submission

{
  title: "MDN Web Docs",
  url: "https://developer.mozilla.org/en-US/",
  description: "Provides information about Open Web technologies including HTML, CSS, and APIs.",
  iconPath: "/resources/learnwebdev/mdn.png"
}

Improving Existing Resources

If you notice any outdated or incorrect information in existing resources, or if you have suggestions for improving them, please feel free to make those updates!

Update Existing Entries

Edit resources.ts to correct or enhance existing resources with better information or improved descriptions.

Provide Feedback

If you have suggestions for improving resource descriptions or other details, please include them in your pull request comments.

Your contributions help keep our resource list accurate and useful for everyone!

If you prefer, you can also create an issue to suggest improvements or report problems.

// For example I want to add a new resource page for 'file converters'
fileconverters: {
  title: "File Converters",
  resourcesList: [
    {
      title: "Online File Converter", // optional, include only if there is another category within the resource page
      links: [
        {
          title: "Convertio",
          url: "https://convertio.co/",
          description: "An easy tool to convert files online.",
          iconPath: "/resources/file-converters/convertio.png"
        },
      ],
    },
  ],
},

Create a New Content File

Create a new file in the contents folder to ensure the added resource is displayed on the page. Name the file appropriately to reflect the resource category or specific resource you are adding.

file-converters.mdx

---
title: File Converters
description: Discover online tools to convert files easily and efficiently.
---
 
<ResourcesCards type="fileconverters" />

And you are good to go! 🎉

Submitting Your Contribution

Commit Your Changes

Stage and commit your changes:

git add .
git commit -m "add: [website name]"

Push to Your Fork

Push changes to your forked repository:

git push --set-upstream origin v2/add-resource
git push

Create a Pull Request

Create a pull request on the original repository, providing a description of the resource and its benefits. GitHub Docs on Pull Requests