Skip to content

Latest commit

 

History

History
577 lines (378 loc) · 31.9 KB

CONTRIBUTING.md

File metadata and controls

577 lines (378 loc) · 31.9 KB

Table of Contents

Contribution Guidelines

Hello 👋 and welcome to Chapter, a project of freeCodeCamp.

We strictly enforce our "Code of Conduct", so please take a moment to read the 196 word policy.

Join our chat to get connected with the project's development team.

Contributing Code

Consider the following options when you are ready to contribute code.

  • GitPod.io - a ready-to-code development environment that launches in the cloud.
  • Traditional Dev Environment - the common method of developing on a computer you control.

Using GitPod

All pull requests will have a GitPod link to allow for quickly opening an "ready-to-code" development environment for that specific issue / task. Follow the GitPod documentation to configure your account and "ephemeral" workspace.

Using a Traditional Dev Environment

This approach is more common and involves the step below to setup and configuring a development environment within a local, virtual, or remote operating system that you own or control.

Step 1 - Fork the Repository on GitHub

'Forking' is a step where you get your own copy of Chapter's repository (a.k.a repo) on GitHub.

This is essential as it allows you to work on your own copy of Chapter. It allows you to request changes to be pulled into the Chapter's repository from your fork via a pull request.

Follow these steps to fork the repository:

  1. Go to the Chapter repository on GitHub.
  2. Click the "Fork" Button in the upper right-hand corner of the interface Need help?.
  3. After the repository has been forked, you will be taken to your copy of the Chapter repository at https://github.com/YOUR_USER_NAME/chapter.

an image illustrating the fork button

Step 2 - Prepare the Terminal and Git Environment

Prerequisite: All commands will be run within a terminal's command line / shell on your development device. Options vary by operating system.

  • Linux - the pre-installed terminal, usually running a bash or sh shell, should work in its default "out of the box" configuration.
  • Mac - the pre-installed Terminal in MacOS, usually running a zsh shell, should work in its default "out of the box" configuration.
  • Windows - options for running a Linux terminal and shell within Windows include:

Prerequisites: Git must exist (run git --version to check) within your development terminal / shell.

  1. Decide if you will authenticate to GitHub using SSH or HTTPS.

    • SSH - uses SSH key authentication instead of a username and password.
    • HTTPS - uses a GitHub username and personal access token (PAT). For security, use a PAT instead of a GitHub password.

  2. Change directories (cd) to wherever you want the Chapter project to be downloaded by Git.

    Note: Windows using WSL + a Linux distro maintains its own file system. Use a sub-directory within the Linux /home/username/ filesystem path. The alternative, using a directory within _C:_ or /mnt/c, will cause everything to run very slowly.

  3. Clone your GitHub fork of Chapter using the SSH or HTTP method you selected above. Replace YOUR_USER_NAME with your GitHub username.

    This command will download the entire Git repository fork into a sub-directory named chapter inside of the current directory. Your forked repository of code will be referred to as the origin .

  4. Configure the Chapter repository as the upstream. Doing this allows you to regularly synchronize code changes from the upstream to your origin fork.

    cd chapter
git remote add upstream https://github.com/freeCodeCamp/chapter.git

  5. Ensure the origin and upstream configuration is correct:

    git remote -v

    The output should look something like below:

     origin    https://github.com/YOUR_USER_NAME/chapter.git (fetch)
 origin    https://github.com/YOUR_USER_NAME/chapter.git (push)
 upstream    https://github.com/freeCodeCamp/chapter.git (fetch)
 upstream    https://github.com/freeCodeCamp/chapter.git (push)
Step 3 - Decide Whether to Run the Application Now, or Later

It's possible to contribute simple changes, like to README.md, without running the application. However, for many situations you will need to get the application running to view pages, see your code in action, and test changes.

If you want to proceed immeditely with running the client, database, and server, then follow the steps in the Running the Application section, below. Then, return here and continue to the next step of this section.

Step 4 - Make Changes and Test the Code 🔥

You are almost ready to make changes to files, but before that you should always follow these steps:

  1. Validate that you are on the main branch

    git status

    You should get an output like this:

     On branch main
 Your branch is up-to-date with 'origin/main'.
 nothing to commit, working directory clean

    If you are not on main or your working directory is not clean, resolve any outstanding files/commits and checkout main:

    git checkout main

  2. Sync the latest changes from the upstream Chapter main branch to your local fork's main branch. This is very important to keep things synchronized and avoid "merge conflicts".

    Note: If you have any outstanding Pull Request that you made from the main branch of your fork, you will lose them at the end of this step. You should ensure your pull request is merged by a moderator before performing this step. To avoid this scenario, you should always work on a branch separate from main.

    This step will sync the latest changes from the main repository of chapter.

    Update your local copy of the freeCodeCamp upstream repository:

    git fetch upstream

    Hard reset your main branch with the chapter main:

    git reset --hard upstream/main

    Push your main branch to your origin to have a clean history on your fork on GitHub:

    git push origin main --force

    You can validate if your current main matches the upstream/main or not by performing a diff:

    git diff upstream/main

    If you don't get any output, you are good to go to the next step.

  3. Create a fresh new branch

    Working on a separate branch for each issue helps you keep your local work copy clean. You should never work on the main branch. This will soil your copy of Chapter and you may have to start over with a fresh clone or fork.

    Check that you are on main as explained previously, and branch off from there by typing:

    git checkout -b fix/update-readme

    Your branch name should start with fix/, feat/, docs/, etc. Avoid using issue numbers in branches. Keep them short, meaningful and unique.

    Some examples of good branch names are:

    • fix/update-nav-links
    • fix/sign-in
    • docs/typo-in-readme
    • feat/sponsors

  4. Edit files and write code on your preferred code editor, such as VS Code.

    Then, check and confirm the files you are updating:

    git status

    This should show a list of unstaged files that you have edited.

     On branch feat/documentation
 Your branch is up to date with 'upstream/feat/documentation'.

 Changes not staged for commit:
 (use "git add/rm <file>..." to update what will be committed)
 (use "git checkout -- <file>..." to discard changes in working directory)

 modified:   CONTRIBUTING.md
 modified:   README.md
 ...

  5. Always Run Code Quality Tools

    Verify all automated code quality checks will pass before submitting a pull request because PRs with failures will not be merged.

    To run the checks locally use npm run lint-and-test OR npm run test:watch to start "watch" mode.

  6. Stage the changes and make a commit

    In this step, you should only mark files that you have edited or added yourself. You can perform a reset and resolve files that you did not intend to change if needed.

    git add path/to/my/changed/file.ext

    Or, you can add all the unstaged files to the staging area using the below handy command:

    git add .

    Only the files that were moved to the staging area will be added when you make a commit.

    git status

    Output:

     On branch feat/documentation
 Your branch is up to date with 'upstream/feat/documentation'.

 Changes to be committed:
 (use "git reset HEAD <file>..." to unstage)

 modified:   CONTRIBUTING.md
 modified:   README.md

    Now, you can commit your changes with a short message like so:

    git commit -m "fix: my short commit message"

    We highly recommend making a conventional commit message. This is a good practice that you will see on some of the popular Open Source repositories. As a developer, this encourages you to follow standard practices.

    Some examples of conventional commit messages are:

    • fix: update API routes
    • feat: RSVP event
    • fix(docs): update database schema image

    Keep your commit messages short. You can always add additional information in the description of the commit message.

  7. Next, you can push your changes to your fork.

    git push origin branch-name-here

    For example if the name of your branch is fix/signin then your command should be:

    git push origin fix/signin
Step 5 - Propose a Pull Request (PR)

When opening a Pull Request(PR), use the following scope table to decide what to title your PR in the following format:

fix/feat/chore/refactor/docs/perf (scope): PR Title

An example is feat(client): night mode.

Scope Documentation
api For Pull Requests making changes to the APIs, routes and its architecture
db For Pull Requests making changes related to database
client For Pull Requests making changes to client platform logic or user interface
docs For Pull Requests making changes to the project's documentation

  1. Once the edits have been committed & pushed, you will be prompted to create a pull request on your fork's GitHub Page. Click on Compare and Pull Request.

    an image showing Compare & pull request prompt on GitHub

  2. By default, all pull requests should be against the Chapter main repo, main branch.

    an image showing the comparison of forks when making a pull request

  3. Submit the pull request from your branch to Chapter's main branch.

  4. In the body of your PR include a more detailed summary of the changes you made and why.

    • You will be presented with a pull request template. This is a checklist that you should have followed before opening the pull request.

    • Fill in the details as they seem fit to you. This information will be reviewed and a decision will be made whether or not your pull request is going to be accepted.

    • If the PR is meant to fix an existing bug/issue then, at the end of your PR's description, append the keyword closes and #xxxx (where xxxx is the issue number). Example: closes #1337. This tells GitHub to automatically close the existing issue, if the PR is accepted and merged.

You have successfully created a PR. Congratulations! 🎉

Running the Application

Prerequisite: Follow steps 1 and 2 of the Contributing Code section, above, before continuing to the next step in this section.

Step 1 - Install Node.js and Dependencies

Prerequisite: Node.js 16+ and npm 8+ must be installed

Note

  • To check Node.js, run node --version and the output should be like v16.#.#
  • If Node.js is not installed, or using an older version, then:
    • (Recommended) Use NVM to manage multiple version of Node.js and run nvm install within the root code directory.
    • Or, install or update the latest version of Node.js. Be sure to close and re-open your terminal for the changes to take effect.
  • To check npm, run npm --version and the output should be like 8.#.#
  • Update npm to the latest version by running npm i -g npm@8 in the root code directory.

Run npm i to install all of the necessary dependencies.

This step will automatically read and process the package.json file. Most notably it:

  • Downloads all Node package dependencies to the node_modules sub-directory
  • Creates the .env configuration file if one does not exist.

    Note: this is done "magically" via the postinstall hook.

Step 2 - Run the App Using Docker Mode OR Manual Mode

There are two approaches to running the Chapter application.

Based on your experience or preference, decide between the two options:

  • Docker Mode: typically easier if you just want to start the application for the first time or don't want to run a local PostgreSQL database on your host computer. It will take longer to "boot up" the container than manual-mode and can be slow to reload some types of code changes.
  • Manual Mode: more of a "hands-on" method, is more lightweight in that it's faster to "boot" and faster to refresh for some code changes, requires more knowledge of running PostgreSQL and configuring localhost services to play nice with the code.

See Running Remotely if you are using a remote server.

Docker Mode

Prerequisite: Docker must exist on your system:

Ensure the Docker tools are installed:

  • Docker using docker --version and it should output something like Docker version 19.03.13...
  • Docker Compose using docker-compose --version and it should output something like docker-compose version 1.28.5...

Make sure DB_PORT=54320 is set in .env.

Run Docker Compose docker-compose up from the root code directory and wait for the successful output as shown in the following example.

Note: This could take minutes for each line to appear.

db_1      | ... LOG:  database system is ready to accept connections
client_1  | ready - started server on http://localhost:3000
app_1     | Listening on http://localhost:5000/graphql

Once Docker is running:

  • The server will automatically restart anytime you save a .ts or .js file used by the server.
  • You can run any command within the container by prefixing it with docker-compose exec app, e.g. docker-compose exec app npm install express
  • If you, or someone else via a commit, updates Dockerfile or the contents of its build directory, run docker-compose build to get the new image. Then, run docker-compose up to start the container's services.

Manual Mode

This is a much lighter development footprint than Docker Mode, but you will need to manually manage the client-server, database, and API server.

Prerequisite: PostgreSQL must exist and be configured.

Set DB_PORT=5432 in .env.

Run npm run both to start the api-server and client-server:

Step 3 - Prepare the Database for Development The database may be empty and / or need to be recreated to get the last schema changes.

See the Initializing the Database section, below, before continuing to the next step in this section.

Step 4 - View the Running Application Once the app has started you should be able to pull up these URLs in your web browser:

Note, MailHog is not started automatically in manual mode. The easiest way to do that is via Docker: docker run --rm --network host mailhog/mailhog, but if you prefer to install it manually, instructions are on their repository

Adding a New Feature

In order to understand where to start, it may help to familiarize yourself with our tech stack. For more details:

Tech Stack Overview

The database we use is PostgreSQL, which we interact with via Prisma. Prisma maps between our database and our code, providing a fully type-safe way to interact with the database. The Express server itself uses Apollo GraphQL server to handle requests from the client. Apollo needs to know the GraphQL schema and we define that by using TypeGraphQL since it lets us automate schema generation and uses decorators for a clean syntax.

The Chapter client uses the React framework Next.js with Apollo Client for data fetching. Since we are generating a GraphQL schema we can use GraphQL Code Generator to convert the schema into a set of TypeScript types and, more importantly, functions to get the data from the server. As a result we know exactly what we're allowed to request from the server and the shape of the data it returns.

Where to Find the Code

  • The database schema is defined in server/prisma/schema.prisma
  • GraphQL object types are defined by files in server/src/graphql-types
  • Resolvers for the GraphQL queries are defined in server/src/controllers
  • The client accesses the data via hooks defined in client/src/generated/generated.tsx
  • To create new hooks, modify queries.ts and mutations.ts files in client/src/modules/**/graphql
  • Client pages are defined according to Next.js's routing e.g. client/src/pages/dashboard/events/[id]/edit.tsx handles pages like /dashboard/events/1/edit
  • Cypress test coverage spec files should go in /cypress/integration, roughly mirroring the client pages pattern

Where to Find the Issues

This is a good place to go if you are looking to get started.

Frequently Asked Questions

What do we need help with right now?

We are in the early stages of development on this new application, but we value any contributions and insights. In order to prevent duplication, please browse and search our "Good First Issue" list and existing issues.

Please join our chat to stay in the loop.

I found a typo. Should I report an issue before I can make a pull request?

For typos and other wording changes, you can directly open pull requests without first creating an issue. Issues are more for discussing larger problems associated with code or structural aspects of the application.

I am new to GitHub and Open Source, where should I start?

Please read our How to Contribute to Open Source Guide.

Feel free to ask us questions on our "Good First Issue" list or join our chat. Please be polite and patient and our community members will be glad to guide you to next steps.

When in doubt, you can reach out to current lead(s):

Name GitHub Role
Oliver Eyton-Williams @ojeytonwilliams Project Lead
Jim Ciallella @allella Documentation, Newbie Questions, & Schema
Fran Zeko @Zeko369 Admin UI, routes, models, and data migrations
Ayotomide Oladipo @tomiiide Public-facing client pages / forms
Timmy Chen @timmyichen API
Patrick San Juan @pdotsani Google Authentication
Jonathan Seubert @megajon Email
Vaibhav Singh @vaibhavsingh97 Heroku 1-click deployment
Quincy Larson @QuincyLarson Executive Lead

You are a champion :).

How do I enable CodeSee?

Copy the client/.example.env.local to client/.env.local.

CodeSee is a developer tool that helps with debugging and understanding the application as it's used. When you first start Chapter, after creating .env.local, you will see a red eye. If you click on it you can register with CodeSee. After that the eye turns blue and lets you start and stop recording.

To learn more, take a look at their docs or just click the button and find out.

How do I work with dependencies?

The client and server are npm workspaces. This means that adding and removing packages work slightly differently from the usual. All that changes is that commands are run from root with the -w=name-of-workspace flag.

For example, to add a new express to the client, run npm i -w=client express. Similarly, to remove it, run npm un -w=client express.

Updating dependencies

We rely on renovate to update dependencies automatically.

Server-side Technical Documentation

API Specification

We use GraphQL to define the API structure of the application.

The GraphQL Playground has "Docs" and "Schema" tabs on the right side of the page. You can see them:

.env Configuration File

An important, local .env configuration file exists in the root code directory. It's used to store environment variables and their associated values.

Any changes to .env will not and should not be committed into your origin fork or the Chapter upstream. Plus, a .gitignore rule exists to prevent it. Do not remove this rule or otherwise attempt to commit your .env to any Git repository.

Keeping your .env out of the repositories is important because the file will contain "secrets" (usernames, passwords, API keys) and other values which are specific to you and your local development environment.

The .env file is automatically created via the Running the Application section when you follow Step 1 - Install Node and Run npx.

This configuration pattern is based on the dotenv package and is also popular in other frameworks and programming languages.

The initial values of the .env will be copied from the .env.example file. However, you should not attempt to add any of your personal configuration values / secrets to the .env.example file. The purpose of .env.example is as a template to declare any variable names the application will need and any values in it are "dummy" / example values purely as a guide to help other developers with their .env file.

Database

PostgreSQL is our database and Prisma is used to map tables to JS objects.

Schema

Our database schema and ER Diagrams are available online using a custom GitHub pages domain using the SchemaSpy format.

Updates to the gh-pages branch and online schema are automatically triggered by commits to the main branch.

Username and Password

  • Set your specific values in .env.
  • For security, it's ideal to change the username and password from the default values.

Host and Port

  • In Docker Mode, the Docker database container will be exposed to the host computer on Host: localhost and Port: 54320. Thus, avoiding potential port conflicts in the case your computer is running PostgreSQL locally for other projects.
  • In Manual Mode, the PostgreSQL port will be as you configured it, the default being Host: localhost and Port: 5432
  • If you're using a remote PostgreSQL server, like ElephantSQL, then the Host and Port will be provided by the service. You'll also need to update the DB_URL value in .env.

Admin Tools

  • pgAdmin, Postico or Table Plus, can use your mode's Host and Port values as described above.
  • psql Client
    • In Docker Mode - psql -h localhost -p 54320 -U postgres. You don't have to run docker-compose exec... commands to "talk" to the PostgreSQL container.
    • In Manual Mode - psql -h localhost -p 5432 -U postgres

Using Prisma and NPM

Our DB commands closely mirror their Rails counterparts (there isn't anything quite similar to ActiveRecord and RailsCLI in node yet, so till then #rails 🚋 )

npm run db:seed -> rake db:seed npm run db:reset -> rake db:reset

Initializing the Database

If starting the application for the first time, or syncronizing with the latest development changes, then the following must occur

  • drop the database - to delete all the structure and data
  • sync the database - to structure by setup tables based on the schema
  • seed the database - development is easier with a database full of example entities. The process of creating example entities in the database is called seeding

The npm run db:reset command will do all three tasks by running npm run db:sync and npm run db:seed sequentially. It also builds the server, since db:sync needs the compiled JavaScript to run.

Troubleshooting: If using ElephantSQL you may have to submit each of these commands individually.

Creating a new table

The prisma.schema file is the single source of truth for the database schema.

Syncing the Schema

  • In development, run the npm run db:sync command.

Creating a Migration

The database is currently undergoing a re-write and we are using prisma db push to keep the database in sync with the schema. Once this is complete, we will update the scripts with the migration workflow.

Running Remotely

When not running locally, the client needs to be passed the server's location by changing your .env file to include NEXT_PUBLIC_APOLLO_SERVER=<https://address.of.graphql.server:port>. For example, if you started Chapter with npm run both and hosted it on https://example.com then the address will be https://example.com:5000.

Troubleshooting

Visit our chat for assistance. Or, create an issue for new bugs or topics.

If you see a JsonWebTokenError in the console, it's likely that you need to clear the token from your browser's local storage.