move3d

h1. Instructions for developers

> See for [[CodingRules|Coding Rules]], here is for setting up your workspace.

The new main repo for move3d is here now (at least for us). Project admins are in charge of keeping it up to date with the official move3d repos (on trac.laas.fr). We will work with a pull request system, and try to involve everyone in the reviews, to ensure the best possible quality for each part and aspect of move3d.

So, where to start? You will have to setup your workspace to use these repos instead of the trac.laas.fr ones, and use the workflow required for this project management system.

h2. Workspace set-up

h3. Change remote

Short version: in git, a remote is a server.

You will change trac.laas.fr to this repo on your local copy using git commands. So, cd to your move3d(planner/hri/studio) local copy and do the following:

<pre>

git remote set-url origin ssh://git@redmine.laas.fr/laas/users/jwaldart/move3d/[planners, hri, libmove3d, studio].git

</pre>

@origin@ is the default name usually given to remotes, esp. when using @git clone@. Yours is maybe different, use @git remote show@ to check the list of remotes and @git remote show <name>@ to see details.

You may want to add a remote instead of changing origin, use the @git remote add@ command instead:

<pre>

git remote add redmine ssh://git@redmine.laas.fr/laas/users/jwaldart/move3d/...

</pre>

h3. Add remote for pushing

You first need to create your own remote repo, where you will push your changes, and from which project maintainers will pull when you requet it. You then add it to the remotes:

<pre>

git remote add perso <url>

</pre>

You will push to it using @git push perso <branch>@ where @<branch>@ is the branch you want to push *to* (usually master).

You will pull form the main repo: @git pull origin <branch>@

*TODO*: how to set default pull/push destinations.

h2. Workflow

h3. Pull-request

Once you modifications are done and you are ready to publish your work, first do some checks, be sure it successfully builds, and push it to your personal repository.

Then go to the redmine page of the main project and click the "new issue" tab ("Nouvelle demande" (fr)). Create a new pull-request and fill the form. Do not forget to specify the url of your personal repo (either hosted by redmine or on any machine at LAAS for instance) and the branch you want the maintainer to pull from.

Specify the assignee, and add any person you think can be interested by your work.

h3. Review

*this is a proposal*

h4. if you have uncommitted work, stash it first:

<pre>

git stash

</pre>

(don't forget to unstash it at the end with @git stash pop@)

h4. Create a new branch to put the work of the developer for the review:

<pre>

git checkout -b review <redmine-remote>/<main-branch>

</pre>

(_e.g._ @git checkout -b review origin/master@ or @git checkout -b review redmine/master@ according to your configuration)

You are now in the branch @review@:

<pre>

$ git branch

  master

* review

</pre>

The state is the one from the repo, in the branch you indicated. (use @git log@ to confirm that) Your latter modifications aren't present.

h4. Pull the work of the developer into this branch:

<pre>

git pull <url> <branch>

</pre>

@<url>@ and @<branch>@ are the one indicated by the developer, they point to its own repository and the branch he wants you to pull _from_

h4. Review

You have the state to be reviewed. Read, compile, test, give your opinion clicking on "edit" in the pull request. In the text field that appears you can put your comments. You change the status to "feedback" for instance to indicate that you have reviewed the code.

h4. Accepting the pull-request

If enough positive advices are collected in the pull-request, it can be pulled into the main repository (here). To do so, push the branch @review@  into the desired branch on the redmine remote:

<pre>

git push <remdine-remote>/<branch>

</pre>

_e.g._ @git push origin/master@

h4. Go back to your own work

<pre>

git checkout master

[ git stash pop ] #only if you stashed something before changing to the branch @review@

</pre>

Will put you back into the state you were before the starting the review.

<pre>

git branch -d review

</pre>

Will delete the branch @review@. git should refuse, invoking an excuse like "the branch review is not merged in master". Here you have the choice to

force the deletion by asking louder: @git branch -D review@ or to actually do what git suggest, _i.e._ merging the branch into master:

<pre>

git merge review

</pre>

This will pull the work you reviewed in your master branch.

As would @git pull origin master@ if the pull-request has been accepted and pushed into the main remote.

---