Thank you for your interest in contributing to the Gunyah Hypervisor project! Your support is essential for keeping this project great and for making it better.
- Please read our Code of Conduct and 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/gunyah-hypervisor/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.
IMPORTANT: 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.
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.
- For Python we follow pep8
- For C, a similar style to Linux kernel coding style, but we do encourage to use brances even for single statements. A definitive LLVM 12
.clang-formatfile is provided and used by CI style checkers. Please apply clang-format to your files by running this command:git ls-files -- '*.[ch]' | xargs $LLVM/bin/clang-format --style=file -i
- 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.
- Every commit must be signed with the Developer Certificate of Origin (by adding the
-soption to yourgit commitcommand). - 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.
Contributors should develop on their own fork on branches based off of the develop branch and then pull requests should be made into the upstream develop branch.
Go to https://github.com/quic/gunyah-hypervisor and clone or fork the repo using these instructions.
Sync your fork with the latest from the upstream repository.
Get the Gunyah Hypervisor code as follows:
git clone https://github.com/YOUR_USERNAME/gunyah-hypervisor.git
IMPORTANT: Setup your pre-commit and commit-msg hook using the following way:
cd gunyah-hypervisor
ln -s $(realpath -s .githooks/pre-commit) .git/hooks/pre-commit
ln -s $(realpath -s .githooks/commit-msg) .git/hooks/commit-msg
Start a new issue on https://github.com/quic/gunyah-hypervisor/issues.
Create a branch for your feature in your local checkout
cd gunyah-hypervisor
git checkout -b branch_short_feature_description
Now you may begin development. Once your development is complete, please ensure that the code builds successfully, that the clang-format has been applied and that the hypervisor boots and the primary VM starts successfully using the instructions in the next sections.
Follow these steps to build the code:
To test that the hypervisor boots and the primary VM starts successfully use these instructions:
Commit the code and push it to 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 (using DCO sign-off as described above):
git commit -s
<add interactive commit message>
To push your branch to your github fork (e.g. origin):
git push origin branch_short_feature_description
Before merging, it is recommended that you update your branch to the latest in branch develop using the following steps:
git fetch
git checkout develop
git pull origin develop
git checkout branch_short_feature_description
Rebase your changes:
git rebase develop
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
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. Merge commits within PRs are not permitted.
See these pages for more 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
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.
- Go to your forked repo page
https://github.com/YOUR_USERNAME/gunyah-hypervisorand click "New Pull Request". - Under "compare changes", select the base (destination) repository as
quic/gunyah-hypervisorand the branch asbase:developto the left of the arrow. - Under "compare changes", select the head (source) repository as
YOUR_USERNAME/gunyah-hypervisorand the branch asbase:branch_short_feature_descriptionto the right of the arrow. - Click "Create Pull Request" which will initiate the PR and take you to the PR page.
- 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 (optional). This person is usually the code submitter.
- Wait for the outcome of the continuous integration (CI) build and test job, and for any review feedback from the project maintainers.
NOTE: as described above, please obtains agreement from maintainers before submitting large changes or new features.