-
Notifications
You must be signed in to change notification settings - Fork 14
Contributing
- We use the Github flow, so all code changes happen through pull requests only.
- Each pull request must be approved by at least one member who is not in the authors of the change.
- A pull request will be merged only when it successfully passes all the automated tests.
- A pull request must address only one feature/issue unless it fixes multiple related issues together.
- It is recommended that each PR be linked to some issue or its subtask. If the issue does not exist, then consider creating it first.
Read the next section to get familiar with contribution workflow.
In order to download necessary tools, clone the repository, and install dependencies via yarn, you need network access.
You'll need the following tools:
- VSCode
- Git
- Node.JS, x64, version >=18.15.x and <19
- Yarn 1, version >=1.10.1 and <2, follow the installation guide
Follow the Commit Signing guide.
First, fork the TPC backend repository so that you can make a pull request. Then, clone your fork locally:
git clone https://github.com/<<<your-github-account>>>/tpc-backend.git
Occasionally you will want to merge changes in the upstream repository (the official code repo) with your fork.
cd tpc-backend
git checkout main
git pull https://github.com/Web-Team-IITI-Gymkhana/tpc-backend.git main
Manage any merge conflicts, commit them, and then push them to your fork.
Note: The tpc-backend repository contains a collection of GitHub Actions that help us with triaging issues. As you probably don't want these running on your fork, you can disable Actions for your fork via https://github.com/<<Your Username>>/tpc-backend/settings/actions.
Install and build all of the dependencies using Yarn:
cd tpc-backend
yarn
The best way to start with the main code base is to fix some existing bugs. Peruse the [“Easy to fix” issues](add a link) in the issue tracker and see if one interests you. If you’d like to try to fix it, then create a message in the issue saying that you’d like to work on it. If it isn’t clear how to fix it, ask for suggestions on how to do it in the issue itself or on the discord.
The first thing to do before making changes to the code is to make a branch in git.
Remember, never commit to main. main should only be used to pull in upstream changes from the main Web-Team-IITI-Gymkhana/tpc-backend repo. If you commit to main, it will be difficult to pull these changes in, and it will also be difficult if you wish to make more than one pull request at a time.
First pick a name for your branch. See Branch names below. To create and checkout (that is, make it the working branch) a new branch run
# Pull any upstream changes from the main tpc-backend repo first
git checkout main
git pull
git branch <your-branch-name>
git checkout <your-branch-name>
The last two commands can also be combined into a single command:
git checkout -b <your-branch-name>
To view all branches, with your current branch highlighted, type:
git branch
And remember, never type the following commands in main: git merge, git add, git commit, git rebase. If you made some commits to your local main by accident, you will have to hard reset to drop the commits.
Use a short, easy to type branch name that somehow relates to the changes. Remember that developers who wish to try out your code will need to type your branch name in the command line to do so.
Avoid using issue numbers in branch names as these are not easy to type and they won’t really be indicative of what the change is about without looking up the issue.
Some examples of good branch names are
fix-solve-bug
typo-fix
core-improvements
add-simplify-tests
Ultimately the branch name is not that important, so don’t spend too much time thinking about it. It’s only function is to distinguish the code for this contribution from other contributions you may make.
Once the changes are ready, you should commit them. You can check what files are changed:
git status
Check total changes:
git diff
If you created any new files, add them with:
git add new_file.py
You are ready to commit changes locally. A commit also contains a commit message which describes it. See the next section for guidelines on writing good commit messages. Type:
git commit -m <commit message>
Also with the help of option -a you can tell the command commit to automatically stage files that have been modified and deleted, but new files you have not told git about will not be affected, e.g.,:
git commit -a
When making your fix, keep in mind there are several requirements that every contribution should follow:
Contributions must have sufficient code quality to be accepted. There are some code quality checks that will run automatically on the CI once you create a pull request, but you can also run them locally with
Additionally, all tests are required to pass. The CI will automatically run the tests, but you can also run them yourself.
Once you submit your pull request, you should check the GitHub Actions checks once they are complete to see if there are any test failures. If there are, you will need to fix them before the pull request will be accepted.
All new functionality should be tested. If you are fixing a bug, it should be accompanied with a regression test. That is, a test that would fail before the bug fix but now passes. Often you can use a code example from an issue as a test case, although it is also OK to simplify such examples or to write your own, so long as it tests the issue in question.
Tests follow a simple pattern, which should be apparent from reading the existing test files.
All new methods, functions, and classes should have a docstring showing how to use them.
The docstring style guide has more details on how to format examples in docstrings.
Once the changes are ready, you should commit them.
A lot of editors can create some configuration files, binary files, or temporary files in your SymPy directory, which should be removed before merging your commits.
Tracking down individual files can be cumbersome.
You may think of using .gitignore, however, editing the .gitignore itself would have the agreement from the community.
Using .git/info/exclude would be the best, because it is only applied locally.
https://help.github.com/en/articles/ignoring-files
The commit message has two parts: a title (first line) and the body. The two are separated by a blank line.
Commit messages summarize what the commit does. Just as with the code, your commit messages will become a permanent part of the project git history. So you should put some effort into making them high quality. Commit messages are intended for human readers, both for people who will be reviewing your code right now, and for people who might come across your commit in the future while researching some change in the code. Thus, include information that helps others understand your commit here, if necessary.
- Make sure to leave a blank line after the summary
- Use plain English. Write in complete sentences.
- Describe what actually changed. Don’t just write something like Modified abc.js. People can already see what files are modified from the commit diff. What the message is there for is to tell them what the diff actually does, so they don’t have to try to figure it out. Similarly, although relevant issues should be cross-referenced as noted above, the message should contain enough of a basic summary that people can understand what is going on without having to look up the issue. The issue can provide more detailed context for people who are interested.
- Try to avoid short commit messages, like “Fix”, and commit messages that give no context, like “Found the bug”. When in doubt, a longer commit message is probably better than a short one. Avoid using the -m switch to git commit to write a commit message on the command line. Rather, let it open your editor so you can write a longer commit message.
- Give an overview of what the commit does if it is difficult to figure out just from looking at the diff.