Skip to content

Workflow

Jump to bottom
geisserf edited this page Oct 25, 2022 · 25 revisions

Development workflow

To continue development of the PROST planner, we use an additional (private) development repository prost-dev. If you have not been granted access so far please write an email to Thomas Keller.

Additionally, we use the issue-tracker of the (non-dev!) repository to discuss all plans, changes and progress. As the repository is public, the issue-tracker is public as well.

If you are about to develop some enhancement or fix some bug, you should stick to the following workflow:

  1. If there is no issue in the issue-tracker for your bug or feature, open one.

  2. Switch to the default branch of the prost development repository ($ git checkout master) and update to the latest version ($ git pull).

  3. Create a new branch. If the issue you are working on is issue #x in the issue tracker, name the branch issue-x. Please make sure that the name is (really!) the word "issue", followed by a minus sign, followed by the number. Assuming you work on issue 42, the following command creates the correct (local) branch: $ git checkout -b issue-42.

  4. To be able to determine which commits belong to which issue even after merging into master, every commit message in issue branch issue- must start with "Issue-: " followed by a text explaining what was done.

  5. We recommend to follow a test-driven development workflow. A tutorial on how to add unit tests in the planner can be found here.

  6. Resolve the issue in the branch. If there are open questions, discuss in the issue-tracker of the prost repository.

  7. Always make sure that your changes are compatible with the coding style.

  8. After you have finished your implementation, make sure your issue-branch is up to date with the master branch. First, make sure that the master branch is up to date. Then, find out if your branch has any conflicts with master by executing

    git merge --no-commit --no-ff master
git merge --abort

    If the issue-branch is up to date (i.e., if the HEAD of the master branch is the revision where your issue-branch branches from), we recommend to run

    git rebase --interactive

    and clean up your commit history (this doesn't perform a rebase since you do not provide a target, but the --interactive option allows you to mess with the commits in the branch). (TODO: If the issue has been addressed not just by you and you have already pushed to the repo, this can be tricky. Update this after we have some experience for this case.) In particular, make sure that every commit starts with "Issue-: ", i.e., the name of the issue you are working on, followed by a colon and a white space. It might sometimes also make sense to squash several commits into one, which is also something that can be done at this point.

    If the issue-branch is not up to date, there are two options to do so: you can either merge the master branch into your issue-branch, or you can rebase your issue-branch to the HEAD of the master branch.

    In case there is no conflict, rebase your issue-branch with

    git rebase --interactive master

    The --interactive option again gives you the chance to clean up your commit history as described above. After having performed the rebase, you need to push your changes to the github repo with

    git push --force

    where the force option is necessary if you are rebasing commits that were already pushed to the repo before (because the rebase rewrites the repo history in this case).

    If there are conflicts, you are free to merge the master branch into your branch instead of performing a rebase, but you can also decide to perform a rebase (in that case, follow the procedure described before). If you decide to merge, we still recommend to clean up your commit history as descibed above. Afterwards, run

    git merge master

    and resolve all conflicts generated by the merge. In this case, you can push the changes as usual with

    git push.

  9. If you would like to have someone look at your code even though the issue isn't fixed yet, find a reviewer who agrees to review your code and use a pull request to discuss the current state of the work. The pull request is declined at the end of the discussion.

  10. Once you implemented everything make sure that your branch is up to date with the default branch. This can be achieved with git rebase master. Manage all conflicts that arise.

  11. Before the final review, run experiments. Make sure to use meaningful configurations. If in doubt, it makes sense to have configurations such that all of the following THTS ingredients are included at least once:

    • Action Selection: UCB1
    • Outcome Selection: MC, UMC
    • Backup Function: MC, MaxMC, PB
    • Initializers: Expand, Single
    • Heuristic for Initializers: IDS, Uniform, MLS, RandomWalk
    • Recommendation Functions: EBA, MPA
    • Also make sure to use the IPC2011 and IPC2014 configurations. If the planner becomes significantly worse, find out why this is the case and fix it.

  12. Find a reviewer for the final review and submit a pull request.

  13. Discuss the implementation with that reviewer and make final adaptions based on the discussion. In some cases, it might make sense to divide the requested changes into subtasks that are dealt with in temporary branches that branch off the issue branch. As a naming convention, we name these branches issue--review-, where is the current issue and an increasing counter starting with 1. The advantage is that the reviewer can easily have a look at the changes again in a new pull request that compares issue- with issue--review-. Make sure that commits in this new branch do not start with "Issue--review-:", but still with "Issue-:". When everyone involved is happy with the subtask, we merge the branch issue--review- back into issue- with a "fast-forward" merge, i.e. such that there is no separate commit message for the merge. In the case that the branch issue--review- branches off the head of issue-, this is possible with

    git checkout issue-<num>
git merge --ff-only issue-<num>-review-<num2> 
git push
git push -d origin issue-<num>-review-<num2>
git branch -d issue-<num>-review-<num2>

    If someone worked on the issue- branch in the meantime, rebase the issue--review- branch to the head of issue- beforehand (untested).

  14. If anything important comes up during discussion (either in the pull request between issue- and master, or in a subtask pull request between issue--review- and issue-), make sure to add a note in the issue tracker as the pull request discussion will not be archived.

  15. When the developer and the reviewer agree that the issue is resolved, the reviewer closes the pull request by merging the code into the master branch of the prost-dev repository. Delete the branch after performing the merge (github asks this after having merged).

  16. The reviewer pushes the updated default branch to the prost repository via git push https://github.com/prost-planner/prost master:master or git push git@github.com:prost-planner/prost.git master:master.

  17. The reviewer closes the issue in the issue tracker and adds a link to the hash of the merge commit.

Clone this wiki locally