Thank you for your interest in contributing to Talawa API. Regardless of the size of the contribution you make, all contributions are welcome and are appreciated.
If you are new to contributing to open source, please read the Open Source Guides on How to Contribute to Open Source.
- Contributing to Talawa API
A safe environment is required for everyone to contribute. Read our Code of Conduct Guide to understand what this means. Let us know immediately if you have unacceptable experiences in this area.
No one should fear voicing their opinion. Respones must be respectful.
If you are ready to start contributing code right away, get ready!
- Join our Slack and introduce yourself. See details on how to join below in the Community section.
- This repository has its own dedicated channel.
- There are many persons on the various channels who are willing to assist you in getting started.
- Take a look at our issues (after reading our guidelines below):
- We have a list of good first issues that contain challenges with a limited scope for beginners.
- There are issues for creating tests for our code base. We need to increase reliablility. Try those issues, or create your own for files that don't already have tests. This is another good strategy for beginners.
- There are dormant issues on which nobody has worked for some time. These are another place to start
- There may also be dormant PRs on which nobody has worked for some time!
- Create an issue based on a bug you have found or a feature you would like to add. We value meaningful sugestions and will prioritize them.
Welcome aboard!
We utilize GitHub issues and pull requests to keep track of issues and contributions from the community.
Make sure you are following issue report guidelines available here before creating any new issues on Talawa API project.
Pull Request guidelines is best resource to follow to start working on open issues.
For Talawa API, we had employed the following branching strategy to simplify the development process and to ensure that only stable code is pushed to the master branch:
develop: For unstable code and bug fixingalpha-x.x.x: For stability testingmaster: Where the stable production ready code lies
When multiple developers are working on issues there is bound to be a conflict of interest (not to be confused with git conflicts) among issues, PRs or even ideas. Usually these conflicts are resolved in a First Come First Serve basis however there are certain exceptions to it.
- In the cases where you feel your potential issues could be an extension or in conflict with other PRs it is important to ask the author of the PR in the slack channel or in their PRs or issues themselves why he/she did not write code for something that would require minimal effort on their part.
- Based on basic courtesy, it is good practice to let the person who created a function apply and test that function when needed.
- Last but not the least, communication is important make sure to talk to other contributors, in these cases, in slack channel or in a issue/PR thread.
- As a last resort the Admins would be responsible for deciding how to resolve this conflict.
Code contributions to Talawa come in the form of pull requests. These are done by forking the repo and making changes locally.
Make sure you have read the Documentation for Setting up the Project
The process of proposing a change to Talawa API can be summarized as:
- Fork the Talawa API repository and branch off
develop. - The repository can be cloned locally using
git clone <forked repo url>. - Make sure your code is up-to-date with the main source main. A detailed guide on the same can be found in the Upgrading Code Section.
- Make the desired changes to the Talawa API source.
- Run the app and test your changes.
- If you've added code, then test suites must be added.
- General:
- We need to get to 100% test coverage for the app. We periodically increase the desired test coverage for our pull requests to meet this goal.
- Pull requests that don't meet the minimum test coverage levels will not be accepted. This may mean that you will have to create tests for code you did not write. You can decide which part of the code base needs additional tests if this happens to you.
- Testing:
- Test using these commands (All tests):
npm run test genhtml coverage/lcov.info -o coverage - Test using these commands (Single test):
npm run test -- -t <Name_of_Test> - Here are some useful testing resources:
- Documentation:
- Jest testing documentation
- The organizations.spec.ts test file is a well documented example of what to do for resolver tests.
- Videos:
- Documentation:
- Test using these commands (All tests):
- General:
- Test Code Coverage:
- General Information
- The current code coverage of the repo is:
- You can determine the percentage test coverage of your code by running these two commands in sequence:
npm install npm run test genhtml coverage/lcov.info -o coverage - The coverage rate will be visible on the penultimate line of the
genhtmlcommand's output. - The
genhtmlcommand is part of the linuxlcovpackage. Similar packages can be found for Windows and MacOS. - The currently acceptable coverage rate can be found in the GitHub Pull Request file. Search for the value below the line containing
min_coverage.
- The current code coverage of the repo is:
- Creating your code coverage account
- You can also see your code coverage online for your fork of the repo. This is provided by
codecov.io- Go to this link:
https://app.codecov.io/gh/XXXX/YYYYwhere XXXX is your GitHub account username and YYYY is the name of the repository - Login to
codecov.iousing your GitHub account, and add your repo and branches to thecodecov.iodashboard. - Remember to add the
Repository Upload Tokenfor your forked repo. This can be found underSettingsof yourcodecov.ioaccount. - Use the value of this token to create a secret named CODE_COV for your forked repo.
- You will see your code coverage reports with every push to your repo after following these steps
- Go to this link:
- You can also see your code coverage online for your fork of the repo. This is provided by
- General Information
- After making changes you can add them to git locally using
git add <file_name>(to add changes only in a particular file) orgit add .(to add all changes). - After adding the changes you need to commit them using
git commit -m '<commit message>'(look at the commit guidelines below for commit messages). - Once you have successfully commited your changes, you need to push the changes to the forked repo on github using:
git push origin <branch_name>.(Here branch name must be name of the branch you want to push the changes to.) - Now create a pull request to the Talawa repository from your forked repo. Open an issue regarding the same and link your PR to it.
- Ensure the test suite passes, either locally or on CI once a PR has been created.
- Review and address comments on your pull request if requested.
Before you start contributing to the repository, you ALWAYS need to make sure that your code is up to date with the source repository at PalisadoesFoundation/talawa-api.
To do we will help you setup an upstream and origin for your repository, which will help you contribute code with great ease:-
After cloning your forked repository, your origin remote is pointing to your fork ({{GITHUB USERNAME}}/talawa-api). To stay up to date with the main PalisadoesFoundation/talawa-api repository, add it as a remote called upstream. You'll first need to move into the talawa-api directory that was created by the clone operation.
$ cd talawa-api
$ git remote add upstream https://github.com/PalisadoesFoundation/talawa-api.git
$ git remote -v
origin https://github.com/{{GITHUB USERNAME}}/talawa-api.git (fetch)
origin https://github.com/{{GITHUB USERNAME}}/talawa-api (push)
upstream https://github.com/PalisadoesFoundation/talawa-api.git (fetch)
upstream https://github.com/PalisadoesFoundation/talawa-api.git (push)
The git remote -v command at the end shows all your current remotes.
Now you can pull in changes from PalisadoesFoundation/talawa-api by running git pull upstream {{branch}} and push your changes to your fork by running git push origin {{branch}}.
We have established a clean setup now. We can make any changes we like and push it to this forked repository, and then make a pull request for getting the changes merged into the original repository. Here's a nice picture explaining the process (image source).
For making any changes to original repository, we first sync our cloned repository with original repository. We merge develop with upstream/develop to do this.
This make sometimes require a hard reset, and can be done with the following commands:
git fetch upstream
git reset upstream/develop --hard
Now we make a new branch (with git checkout -b {{ BRANCH_NAME }} ), do the changes on the branch, add and commit them (with git add . && git commit -m {{ COMMIT_MESSAGE }} ), push the branch to forked repository (with git push origin {{ BRANCH_NAME }} --force ), and make a PR from Github interface (from our new branch to the develop branch of PalisadoesFoundation/talawa-api s).
We use a different branch to make changes so that we can work on multiple issues while still having a clean version in develop branch.
On making a PR, we use GitHub actions to check that your code is properly formatted, doesn't have typescript type errors and is properly linted. Here are the checks:-
We make use of official typescript compiler(tsc) to check the codebase for type errors.
To check for type errors use this command:-
npm run typecheck
We make use of eslint to enforce a strict linting convention in code.
To check code for linting issues use this command:-
npm run lint:check
To check and fix lint errors in code use this command:-
npm run lint:fix
Eslint might throw lint errors even after running the lint:fix command as those lint errors require manual intervention to be fixed. You have to fix those lint errors manually.
We make use of prettier to enforce a strict formatting convention in code.
To check code for formatting issues use this command:-
npm run format:check
To fix formatting issues in code use this command:-
npm run format:fix
We are using the package Husky to run git hooks that run according to different git workflows.
We run a pre-commit hook which automatically runs code quality checks each time you make a commit and also fixes some of the issues. This way you don't have to run them manually each time.
If you don't want these pre-commit checks running on each commit, you can manually opt out of it using the --no-verify flag with your commit message as shown:-
git commit -m "commit message" --no-verify
We are also running a post-merge(post-pull) hook which will automatically run "npm install" only if there is any change made to pakage.json file so that the developer has all the required dependencies when pulling files from remote.
If you don't want this hook to run, you can manually opt out of this using the no verify flag while using the merge command(git pull):
git pull --no-verify
- Talawa API currently implement
GraphQL Playgroundas mediator interface to run and test queries directly from the api. Learn more - In development, Apollo Server enables GraphQL Playground on the same URL as the GraphQL server itself (e.g. http://localhost:4000/graphql) and automatically serves the GUI to web browsers. When NODE_ENV is set to production, GraphQL Playground (as well as introspection) is disabled as a production best-practice.
- Note: To access the playground in talawa API append the URL with "/graphql"
If you are participating in any of the various internship programs we ar members of then please read the introduction guides on our documentation website.
There are many ways to communicate with the community.
- The Palisadoes Foundation has a Slack channel where members can assist with support and clarification. Visit the Talawa GitHub repository home page for the link to join our slack channel.
- We also have a technical email list run by freelists.org. Search for "palisadoes" and join. Members on this list are also periodically added to our marketing email list that focuses on less technical aspects of our work.