Github
The forks created from existing Github projects into Nordix namespace uses nordix-dev as default/development branch.
master branch is locked in order to use it as a reference to upstream repo in order to make it easier to compare changes against and rebase as needed.
Please ensure you always for against nordix-dev branch, create your local branches from there, and frequently rebase against master branch.
Sending Pull Requests to Nordix Repos
- Get the project you want to contribute to forked to Nordix namespace on Github.
- This can be done by sending an email to discuss@lists.nordix.org.
- Please include the Github link to the project you want the fork created for.
- Login to Github using your Github username and password.
- Navigate to Nordix namespace and click the name of the project fork you will be contributing to.
- Click "Clone or Download" button on the opening page and grab the URI to clone the repo.
- Clone the repo to your computer.
- git clone <URI>
- Create a local branch to do your work on.
- git checkout -b <branch_name>
- Do your work, commit.
- git add -A .
- git commit -m "Commit message"
- Push your branch to origin
- git push origin <branch_name>
- Go to your Web browser and navigate to the project you did your work
- click Pull Requests tab
- click New Pull Request button
- Change base fork to Nordix/<forked project>
- Change base branch to nordix-base
- Change compare branch to the branch you pushed
- Click Create New Pull Request
- Merge Pull Request if you are done with your work.
Sending Pull Requests to Upstream Repos
- Navigate to the project which the fork was created from
- Click New Pull Request
- Click Compare Across Forks
- Change Base Fork/branch to the project/branch you want to get your changes merged into
- Change Head Fork/branch to the Nordix fork you merged your pull requests into and nordix-dev branch
- Add description for your Pull Request
- Click Create Pull Request
You can experiment with this workflow using Nordix/sandbox repo which is forked from a personal repo fdegir/sandbox for experimentation.
If you find ways to improve the workflow, please do not hesitate to update this page.
Gerrit
If you are working based on Apache licensed upstream project, the work you are doing first needs to land in to Nordix Infrastructure.
In order to achieve this, you should have got the upstream repo imported to Nordix Gerrit so you can rebase your changes against upstream master and do your work on Nordix against nordix-dev branch.
A sample workflow for ONAP based project is listed below so you should be able to follow these steps to do your work and send changes to upstream once you are done.
Deliver to ONAP
- Fetch the latest changes for all branches from central repo to local repo.
git checkout master
git pull --rebase - Create a temporary local delivery branch. origin/master will point at the latest master version
- git checkout –b nordix-dev_delivery origin/master
- Squash all the commits you want to deliver into one and merge, or cherry pick the commit into the temporary local delivery branch.
git merge -–squash origin/nordix-dev (Need to find another way to do this, since there will be too many commits included in the squash merge from the branch after some time. Maybe this can help: https://www.roman10.net/2012/08/03/git-merge-a-range-of-commits-from-one-branch-to-another/)
Or
Copy the "Cherry Pick" option from "Download" drop down on the change's Gerrit page. - Update commit message (see Commit Messages for format) and commit. This will also create a new Change-ID
git commit - Sanity check that the changes seem to be ok
git diff origin/master - Push the new commit to dev in the central ONAP repo, by using "upstream", for review and verification
git push upstream HEAD:refs/for/master
For this to work, an entry similar to the one below is needed int the .git/config file in the repo:
[remote "upstream"]
url = ssh://<username>@gerrit.onap.org:29418/dcaegen2/collectors/datafile.git
fetch = +refs/heads/*:refs/remotes/upstream/* - Move to another branch so the temporary delivery branch can be deleted (git branch shows you the branches you have which you can move to)
git checkout <some other branch> - Remove the temporary local delivery branch
git branch –D nordix-dev_delivery
Uplift a Team Branch
Use this procedure to uplift (merge) the nordix-dev branch after your changes have been merged in to the ONAP repo and synched back to the nordix master branch.
- Fetch latest changes from central repo.
git fetch - Create a temporary branch based on the latest remote
git checkout -b nordix-dev_temp origin/nordix-dev - Perform the merge.
git merge origin/master - Depending on whether you encounter merge conflicts or not:
If there are conflicts you will have to solve them before continuing:
git status
git mergetool
git status
git commit
Remember to clean up the commit message (the default one provided by Git is not recommended)!
The git status command has no practical effect, but it's always good to run to keep track of what is happening. - If there are no merge conflicts Git will automatically commit the merge, but you should amend commit message (the default one provided by Git is not recommended):
git commit --amend
Running the git commit command also has the effect that a change-id is added to the commit message (if not present already). And you need a change-id to be able to push a commit for review. - Send uplift for review and to run verification
git push origin HEAD:refs/for/task/<owner>/<branch> - Go back to team branch.
git checkout task/<owner>/<branch>. - Remove temporary branch
git branch –d task/<owner>/<branch>_temp
When automatic rebase fails
When you run into the situation that you cannot commit in ONAP because a rebase is needed, but the "Rebase" button in Gerrit doesn't work, then rebase your change manually in your local repository.
Note: Cherry-picking a commit on top of a new base is the same as rebasing a commit on top of a new base. It's just a matter of which commit you have checked out before running the command. Cherry-picking is more flexible though and can be used for more than just rebasing.
- Fetch the latest changes for all branches from central repo to local repo.
git fetch - Make sure that latest commit on Nordix master is the same as the latest one on ONAP master. If not, send a mail to the "discuss" mailing list that there might be something wrong with the synch job.
- Create a temporary branch
git checkout -B temp_rebase_branch origin/master - Get the change from Gerrit by using the cherry-pick link on the Gerrit review page
git fetch https://gerrit.onap.org/r/dcaegen2/collectors/datafile refs/changes/69/67269/2 && git cherry-pick FETCH_HEAD - Resolve the rebase conflicts
git mergetool
git cherry-pick --continue - Resubmit to master in ONAP
git push usptream HEAD:refs/for/master - Move to another branch so the temporary rebase branch can be deleted (git branch shows you the branches you have which you can move to)
git checkout <some other branch> - Remove the temporary local delivery branch
git branch –D temp_rebase_branch