Skip to content

Commit

Permalink
Add proper documentation for contributions
Browse files Browse the repository at this point in the history 
Add information about the steps to follow to contribute to fastrpc
project.

Signed-off-by: Ekansh Gupta <[email protected]>
  • Loading branch information
@quic-ekangupt
quic-ekangupt committed Aug 9, 2024
1 parent e473913 commit 756aa9b
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 58 deletions.
189 changes: 132 additions & 57 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,61 +4,136 @@ Hi there!
We’re thrilled that you’d like to contribute to this project.
Your help is essential for keeping this project great and for making it better.

## Branching Strategy

In general, contributors should develop on branches based off of `main` and pull requests should be made against `main`.

## Submitting a pull request

1. Please read our [code of conduct](CODE-OF-CONDUCT.md) and [license](LICENSE.txt).
1. [Fork](https://github.com/quic/fastrpc/fork) and clone the repository.

```bash
git clone https://github.com/quic/fastrpc.git
```

1. Create a new branch based on `main`:

```bash
git checkout -b <my-branch-name> main
```

1. Create an upstream `remote` to make it easier to keep your branches up-to-date:

```bash
git remote add upstream https://github.com/quic/fastrpc.git
```

1. Make your changes, add tests, and make sure the tests still pass.
1. Commit your changes using the [DCO](http://developercertificate.org/). You can attest to the DCO by commiting with the **-s** or **--signoff** options or manually adding the "Signed-off-by":

```bash
git commit -s -m "Really useful commit message"`
```

1. After committing your changes on the topic branch, sync it with the upstream branch:

```bash
git pull --rebase upstream main
```

1. Push to your fork.

```bash
git push -u origin <my-branch-name>
```

The `-u` is shorthand for `--set-upstream`. This will set up the tracking reference so subsequent runs of `git push` or `git pull` can omit the remote and branch.

1. [Submit a pull request](https://github.com/quic/fastrpc/pulls) from your branch to `main`.
1. Pat yourself on the back and wait for your pull request to be reviewed.

Here are a few things you can do that will increase the likelihood of your pull request to be accepted:

- Follow the existing style where possible. **INSERT LINK TO STYLE, e.g. PEP8 for python**
- Write tests.
- Keep your change as focused as possible.
If you want to make multiple independent changes, please consider submitting them as separate pull requests.
- [Before you begin](#before-you-begin)
- [Guidelines](#guidelines)
- [Branching strategy](#branching-strategy)
- [Setup](#setup)
- [Get code](#get-code)
- [Development](#development)
* [Build](#build)
* [Test](#test)
* [Commit](#commit)
* [Branch update](#branch-update)
* [Branch cleanup](#branch-cleanup)
- [Submission](#submission)

## Before you begin
- Please read our [Code of Conduct](CODE-OF-CONDUCT.md) and [License](LICENSE) and ensure that you agree to abide by them.
- For every new feature or bug fix, always start a new issue on https://github.com/quic/fastrpc/issues.
- To contribute a bug-fix, please follow the steps in the next sections without any further discussion.
- To contribute new features, extensions, utility functions or other significant changes, please describe and discuss the change with us via the GitHub issue that you created above. **A pull request (PR) submitted without discussion and agreement with the project maintainers may be subject to rejection, or significant changes may be requested prior to its acceptance.**

## Guidelines
Please follow the guidelines below to increase the likelihood and speed of your PR acceptance:
- Follow the existing style in the file or folder where possible.
- Keep your change as focused as possible. If you want to make multiple independent changes, consider submitting them as separate PRs.
- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
- It's a good idea to arrange a discussion with other developers to ensure there is consensus on large features, architecture changes, and other core code changes. PR reviews will go much faster when there are no surprises.
- Every commit must be signed with the [Developer Certificate of Origin](https://developercertificate.org) (by adding the `-s` option to your `git commit` command).
- Each PR submission will trigger a build, test, code quality check and static analysis processes. Submitters are required to fix all failures and warnings prior to acceptance.

## Branching strategy
Contributors should develop on [their own fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) on branches based off of the `development` branch and then pull requests should be made into the [upstream `development` branch](https://github.com/quic/fastrpc/tree/development).

## Setup
Go to https://github.com/quic/fastrpc and fork the repo using [these instructions](https://help.github.com/en/github/getting-started-with-github/fork-a-repo).

## Get code
[Sync your fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork) with the latest from the upstream repository.

Get the fastrpc code as follows:
```
git clone https://github.com/YOUR_USERNAME/fastrpc.git
cd fastrpc
```
*IMPORTANT:* Setup your pre-commit and commit-msg hook using the following way:
```
cd fastrpc
ln -s $(realpath -s .githooks/pre-commit) .git/hooks/pre-commit
ln -s $(realpath -s .githooks/commit-msg) .git/hooks/commit-msg
```

## Development
Start a new issue on https://github.com/quic/fastrpc/issues.

Create a branch for your feature
```
git checkout -b branch_short_feature_description
```

Now you may begin development. Once your development is complete, please ensure that the code builds successfully and that all tests pass using the instructions in the next sections.

### Build
Follow these steps to [build the code](https://github.com/quic/fastrpc/tree/development?tab=readme-ov-file#build--installation).

Verify that build artifacts got created here:
```
ls ./src/libs/
```

### Test
Run [unit tests](https://github.com/quic/fastrpc/tree/development?tab=readme-ov-file#testing).

### Commit
Commit the code and checkpoint it on your branch using the following procedure.

To display the files that you modified or added:
```
git status
```

To stage new (untracked) or existing files or folders for commit, do the following for each file or folder name that was added or changed:
```
git add <file or folder name that was added or changed>
```

To commit your changes:
```
git commit -s -m "Commit message"
```
>*IMPORTANT:* The -s option is required during the commit step (DCO signoff).
To push your branch to the remote:
```
git push origin branch_short_feature_description
```

### Branch update
Before merging, it is recommended that you update your branch to the latest on development using the following steps:
```
git fetch
git checkout development
git pull origin development
git checkout branch_short_feature_description
```
Rebase your changes:
```
git rebase development
```
Fix any conflicts that may arise. Then complete the rebasing procedure as follows:
```
git status
# Run the next 2 commands ONLY IF you needed to fix any conflicts.
# Run this for each file that you changed
git add <file or folder name that was added or changed>
git rebase --continue
```
Re-build the code on your branch and run all tests. Then update your remote branch:
```
git push origin branch_short_feature_description --force-with-lease
```

### Branch cleanup
It is recommended that you commit code to your branches often. Prior to pushing the code and submitting PRs, please try to clean up your branch by squashing multiple commits together and amending commit messages as appropriate. See these pages for details:
https://blog.carbonfive.com/2017/08/28/always-squash-and-rebase-your-git-commits
https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

## Submission
When you're ready to submit your code, issue a pull request from the branch on your FORK into the develop branch on the upstream repository using these [instructions](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork).
1. Go to your forked repo page `https://github.com/YOUR_USERNAME/fastrpc` and click "New Pull Request".
1. Under "*compare changes*", select the base (destination) repository as `quic/fastrpc` and the branch as `base:development` to the left of the arrow.
1. Under "*compare changes*", select the head (source) repository as `YOUR_USERNAME/fastrpc` and the branch as `base:branch_short_feature_description` to the right of the arrow.
1. Click "*Create Pull Request*" which will initiate the PR and take you to the [PR page](https://github.com/quic/fastrpc/pulls).
- In the PR page, click *Reviewers* on the top left and select one. He/she will receive an email notification.
- In the PR page, click *Assignee* on the top left and select one. This person can be the reviewer or someone else or even the code submitter.
1. Wait for the outcome of the continuous integration (CI) build and test job, and for any review feedback from the project maintainers.
4 changes: 3 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@ Use Hexagon SDK examples to verify. for eg: run calculator_walkthrough.py for va
Hexagon SDK documentation @ https://developer.qualcomm.com/software/hexagon-dsp-sdk.
Linaro documentation @ https://git.codelinaro.org/linaro/qcomlt/fastrpc/-/wikis/Testing-FastRPC.

## Contributions
Thanks for your interest in contributing to FastRPC! Please read our [Contributions Page](CONTRIBUTING.md) for more information on contributing features or bug fixes. We look forward to your participation!

## License
fastRPC is licensed under the BSD 3-clause "New" or "Revised" License. Check out the [LICENSE](LICENSE) for more details.

0 comments on commit 756aa9b

Please sign in to comment.