...
Code Block |
---|
git push -u origin KNOX-nnn |
3. Implement the feature and commit and push as desired. Note that commit messages should include the issue identifier and the issue title (e.g., KNOX-{NNNN} - {JIRA TITLE}).
Code Block |
---|
git commit -am "<short message about commit>" git push |
...
4. To update the branch from master at any time
Code Block |
---|
git pull --rebase origin master |
...
5. To merge the branch back into master, first switch to the master branch and then merge.
Code Block |
---|
git checkout master git merge KNOX-nnn git push |
...
6. After all code has been merged and the branch is no longer needed, it can be deleted remotely with:
...
Code Block |
---|
git branch -d KNOX-nnn |
...
Github Workflow
Recently the Knox project converted our repository to Gitbox. This allows us to merge pull requests directly using the Github interface. In this chapter you can read about the recommended Github workflow on how to use this approach as a Knox contributor/committer instead of the old style JIRA patches.
...
- Fork the project on your Github account at https://github.com/apache/knox if you haven't already
Clone this fork:
Code Block # Replace [forked-repository-url] with your git clone url. This sets up the remote alias "origin" automatically which refers back to your forked repo. $ git clone [forked-repository-url] knox
Set upstream remote:
Code Block $ cd knox $ git remote add upstream https://github.com/apache/knox.git
Make sure that your master branches remote to the newly created upstream. Therefore your local
master
branch will be trackingupstream/master
so when you do agit pull
by default it will look atupstream
:Code Block $ git checkout master $ git branch --set-upstream-to upstream/master
Source code
...
settings in case you already have Knox's source checked out locally
If you are already a Knox contributor and you followed the old contribution flow using JIRA patches you are very likely to have https://github.com/apache/knox checked out locally as follows:
Code Block $ cd [your knox project path] $ git checkout master $ git status On branch master Your branch is up to date with 'origin/master'. nothing to commit, working tree clean $ git remote -v origin https://github.com/apache/knox.git (fetch) origin https://github.com/apache/knox.git (push)
- You also need to fork https://github.com/apache/knox.git on your Github account the same way as described above
To support consistency with the approach we described above the following changes are recommended in your local repository:
Code Block # renaming the existing origin to upstream $ git remote rename origin upstream # adding your forked repository as a new remote with name origin $ git remote add origin [forked-repository-url] $ git remote -v origin [forked-repository-url] (fetch) origin [forked-repository-url] (push) upstream https://github.com/apache/knox.git (fetch) upstream https://github.com/apache/knox.git (push) $ git checkout master $ git branch --set-upstream-to upstream/master
...
Code Block |
---|
# Checkout the branch that needs to sync (i.e. master) git checkout master # Pulling latest changes from upstream remote (assuming your branch does not have any local changes so that remote updates can be fast-forwarded) git pull # Optionally, push missing changes to your forked repo git push origin master |
...
Create a branch named KNOX-#### in your local repository and check it out
Code Block # make sure to track local master branch git chekcoutcheckout master # creating and checking out the new branch locally git checkout -b KNOX-####
Mark the status of the related JIRA as "In Progress" to let others know that you have started working on the JIRA.
- Make changes to the code and commit them to the newly created branch.
- Run all the tests that are applicable and make sure that all unit tests pass
Make changes to the code and commit them to the newly created branch.
Code Block git add [your-changes] git commit -m "KNOX-#### - Your meaningful commit message"
Push your changes. Provide your Github user id and Push your changes. Provide your Github user id and personal access token when asked for user name and password
Code Block git push origin KNOX-####
...
- Navigate to your fork in Github and create a pull request. The pull request needs to be opened against the branch you want the patch to land.
- The pull request title should be of the form KNOX-#### Title, where KNOX-#### is the relevant JIRA number
- If the pull request is still a work in progress, and so is not ready to be merged, but needs to be pushed to Github to facilitate review, then add [WIP] before the KNOX-####
- Consider identifying committers or other contributors who have worked on the code being changed. Find the file(s) in Github and click “Blame” to see a line-by-line annotation of who changed the code last. You can add @username in the PR description or as a comment to request review from a developer.
Note: Contributors do not have access to edit or add reviewers in the "Reviewers" widget. Contributors can only @mention to get the attention of committers. - The related JIRA will automatically have a link to the PR as shown below. Mark the status of JIRA as "Patch Available" manually.
3.3. Travis CI
A Travis CI job is configured to be triggered every time
- a new pull request is created, or
- a new commit is arrivedpushed to an already created PR
The job is configured to perform the following tasks:
- Validate the merge
- Build Knox (using JDK-8 and JDK-11) on AMD64 and ARM64 CPU architectures
- Run unit/integration tests
It is the responsibility of the contributor of the pull request to make sure that the build passes. Pull requests should not be merged if the Jenkins job fails to validate the merge.if the TravisCI job fails to validate the merge.
3.4. GitHub Actions
GitHub Actions is also enabled for the project. It is used as an alternative to Travis CI and might become the main CI in the future.
Pros: It is a bit faster than Travis CI
Cons: it doesn't have non-x86_64 nodes for testing on alternative CPU architectures
4. Review Process
All committers who are invited for review are required to follow the instructions in this page and link their Github accounts with gitbox Gitbox to gain Merge access to apache/knox
in Github.
...
- Other reviewers, including committers can try out the changes locally and either approve or give their comments as suggestions on the pull request by submitting a review on the pull request. More help can be found here.
- If more changes are required, reviewers are encouraged to leave their comments on the lines of code that require changes. The author of the pull request can then update the code and push another commit to the same branch to update the pull request and notify the committers.
- The pull request can be merged if at least one committer has approved it or commented "LGTM" which means "Looks Good To Me" and the Travis CI job validated the merge successfully. If you comment LGTM you will be expected to help with bugs or follow-up issues on the patch. (Remember committers cannot review their own patch. If a committer opens a PR, they should make sure that another committer reviews it.
- Sometimes, other changes might be merged which conflict with the pull request’s changes. The PR can’t be merged until the conflict is resolved. This can be resolved by running
git fetch upstream
followed bygit rebase upstream/[KNOX-####]
and resolving the conflicts by hand, then pushing the result to your branch. - If a PR is merged, promptly close the PR and resolve the JIRA as "Fixed".
...
Code Block | ||
---|---|---|
| ||
svn ci <modified_files> -m "Change comment" |
...
Include Page | ||||
---|---|---|---|---|
|