Skip to content

Commit

Permalink
Merge pull request #49 from ktf/gh-pages
Browse files Browse the repository at this point in the history 
Improved tutorials.
  • Loading branch information
@ktf
ktf committed Jul 6, 2013
2 parents 532ad81 + 2973df7 commit fd128c3
Show file tree
Hide file tree
Showing 5 changed files with 181 additions and 55 deletions.
10 changes: 9 additions & 1 deletion _layouts/default.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@
background: rgb(51,51,51);
color: #ffffff;
}
p {
font-size: 17.5px;
font-weight: 300;
line-height: 1.25;
}
</style>
</head>
<body>
Expand All @@ -40,7 +45,10 @@ <h3 id='quick_start'>Quick start</h3>
<li><a href='index.html'>Main page</a></li>
<li><a href='faq.html'>CMSSW on Github FAQ</a></li>
<li><a href='usercode-faq.html'>UserCode on Github FAQ</a></li>
<li><a href='tutorial.html'>CMSSW Git Tutorial</a></li>
<li>Tutorials:<ul>
<li><a href='tutorial.html'>Proposing changes to CMSSW</a></li>
<li><a href='tutorial-l2-check-topics.html'>Approval process</a></li>
</ul></li>
<li><a href='rosetta.html'>Rosetta Stone</a></li>
<li><a href='troubleshooting.html'>Troubleshooting git</a></li>
<li><a href='advanced-usage.html'>Advanced Usage FAQ</a></li>
Expand Down
Binary file added images/topic-collector-top-bar.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/topic-table.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
118 changes: 118 additions & 0 deletions tutorial-l2-check-topics.mdwn
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
---
title: CMS Offline Software
layout: default
related:
- { name: Project page, link: https://github.com/cms-sw/cmssw }
- { name: Topic Collector, link: https://cern.ch/cmsgit/cmsgit }
- { name: Feedback, link: https://github.com/cms-sw/cmssw/issues/new }
---

## Tutorial: approval process

This tutorial wil guide you through the topic approval procedures, i.e. the common
L2 coordinator workflow.

### Before you start.

Please make sure you registered to GitHub and that you have provided them
a ssh public key to access your private repository. For more information see
the [FAQ](faq.html).

### Go to the Topic Collector to find out pending topics.

The *CMS Topic Collector* is the replacement of the old CVS Tag Collector. It
contains a list of all the open topics for a given release.

You can get it by either going to:

https://cern.ch/cmsgit/cmsgit

or simply by clicking on the "Topic Collector" link at the top of this page.

You'll be prompted with the usual CERN login window, enter there your NICE
username and password, or use your certificate to login.

You'll be presented with a navigation bar showing all the available, open release
series:

![topic-collector-topbar](images/topic-collector-top-bar.png)

### The open topics table.

As stated on the page, the table below the navigation bar refers to the topics
open for the selected release. For example:

![topic-collector-table](images/topic-table.png)

The table is dived in three parts.

* The topic information, i.e. the left part of the table
* The approval process status, i.e. the green, yellow and red icons.
* The available actions, the buttons in the right part of the table.


### Checking a topic

In order to approve or reject a given topic, you need first to test it works as
expected. After you have created a local workarea:

> scram project CMSSW_7_0_0_pre0
> cd CMSSW_7_0_0_pre0/src
> cmsenv

you can merge the topic in it by doing:

git cms-merge-topic <topic-id>

where `<topic-id>` is the number shown in the left-most column, named "Id".

You then need to run the `checkdeps` equivalent via:

git cms-checkdeps -a

this will checkout all the packages which are dependent on the changes you just
merged. You can finally recompile and test the topic:


scram b -j 20
runTheMatrix.py -s
<test-at-will>

at minimum you should check that the short matrix actually works.

Notice you can specify `git-cms-merge-topic` as many times as you want, however
one big difference with CVS is that there is no need of dependency tracking,
git branches, which are the backend of a topic, already include the full set of
additions a developer had in his area, therefore each topic is self contained.
If something does not compile, it really means that the developer submitted
something which is not what he tested.

### Signing a topic

Once you are done with your tests, you can sign or reject a topic by going back
to the topic collector and clicking on the "Sign" or "Reject" button.

Notice that when you reject a topic, it will have a red circle next to it, but
it will not disappear from your sight. It will be up to the release manager to
close it or up to the developer to update it's changes and correct it.

### Commenting on topics

You can comment on topics, by clicking on their title in the table and adding a
comment in the standard GitHub GUI.

### Similarities with the old CVS workflow

Assuming you are familiar with the old, CVS based, workflow, nothing is
particularly different if you do the equation

`Tagset == Topic`

### Pull requests

Topics are nothing else than glorified [GitHub Pull
Requests](https://help.github.com/articles/using-pull-requests) the only
CMS-specific addition is that they have CMS specific approval information
attached to it.

[topic-collector]: https://cern.ch/cmsgit/cmsgit
108 changes: 54 additions & 54 deletions tutorial.mdwn
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ questions please have a look at the [FAQ](faq.html) pages.

### Before you start.

> Please make sure you registered to GitHub and that you have provided them
> a ssh public key to access your private repository. For more information see
> the [FAQ](faq.html).
Please make sure you registered to GitHub and that you have provided them
a ssh public key to access your private repository. For more information see
the [FAQ](faq.html).

### Create a CMSSW area

> Set up the work area just like you used to.
Set up the work area just like you used to.

> scram project CMSSW_6_2_0_pre8
> cd CMSSW_6_2_0_pre8/src
Expand All @@ -37,31 +37,31 @@ The src directory is populated with just what we asked for (here
> ls Tutorial/Test/bin
BuildFile.xml

>By default it would simply use the current release tag (e.g.
>CMSSW_6_2_0_pre8). At any point you can list the available branches via `git
>branch`.
By default it would simply use the current release tag (e.g.
CMSSW_6_2_0_pre8). At any point you can list the available branches via `git
branch`.

> git branch
* from-CMSSW_6_2_0_pre8

> the `*` next to the branch name will tell you which one is the current one.
> The name of the branch is meant to show you the tag which was used as a base
> for the branch.
the `*` next to the branch name will tell you which one is the current one.
The name of the branch is meant to show you the tag which was used as a base
for the branch.


### Create a new topic branch and move to it:

> In order to simplify your workflow, the best thing to do is to branch
> immediately and assign a mnemonic name to your newly created branch, so that
> you can track what you were doing in an easier way.
In order to simplify your workflow, the best thing to do is to branch
immediately and assign a mnemonic name to your newly created branch, so that
you can track what you were doing in an easier way.

> git checkout -b my-new-feature
Switched to a new branch 'my-new-feature'

> For example you could call your branch "new-hlt-menu-XYZ",
> "bugfix-for-clustering", etc. Compared to CVS, `git checkout <branch>` means
> *"Make `branch` the current `branch` in the local work area"*.
> The `-b` option is needed to create the branch if it does not exists.
For example you could call your branch "new-hlt-menu-XYZ",
"bugfix-for-clustering", etc. Compared to CVS, `git checkout <branch>` means
*"Make `branch` the current `branch` in the local work area"*.
The `-b` option is needed to create the branch if it does not exists.


### Modify sources and commit.
Expand All @@ -72,84 +72,84 @@ The src directory is populated with just what we asked for (here
[my-new-feature 8135042] Test feature
1 file changed, 1 insertion(+)

> You have just committed to your **LOCAL** copy of the repository.
You have just committed to your **LOCAL** copy of the repository.

### Show remote repositories

>Git supports multiple remote repository. In particular we will use:
>
>- *my-cmssw*: your personal repository, used to propose changes
>- *official-cmssw*: read only authoritative CMSSW sources
>
>To show what remotes are available you can use `git remote show`:
Git supports multiple remote repository. In particular we will use:

- *my-cmssw*: your personal repository, used to propose changes
- *official-cmssw*: read only authoritative CMSSW sources

To show what remotes are available you can use `git remote show`:

> git remote show
my-cmssw
official-cmssw

>The general workflow for development will be the following:
>- Fetch official sources from `official-cmssw`.
>- Create a feature branch and add your additions on top.
>- Create a [Pull Request](https://help.github.com/articles/using-pull-requests).
>
> Each pull request you do to the [official CMSSW
> repository](https://github.com/cms-sw/cmssw) will also appear in the
> [CMS Topic Collector][topic-collector], together with the approval information.
The general workflow for development will be the following:
- Fetch official sources from `official-cmssw`.
- Create a feature branch and add your additions on top.
- Create a [Pull Request](https://help.github.com/articles/using-pull-requests).

Each pull request you do to the [official CMSSW
repository](https://github.com/cms-sw/cmssw) will also appear in the
[CMS Topic Collector][topic-collector], together with the approval information.

### Push all your work to your private github repository

> Your private repository can be found at:
Your private repository can be found at:

https://github.com/<your-username>/cmssw

> If you have not set it up yet, do so now by [clicking
> here](https://github.com/cms-sw/cmssw/fork). You can publish branches to it
> by doing:
If you have not set it up yet, do so now by [clicking
here](https://github.com/cms-sw/cmssw/fork). You can publish branches to it
by doing:

> git push my-cmssw <branch-name>

> in this case:
in this case:

> git push my-cmssw my-new-feature

> **You need to PUSH YOUR changes** to make them available to others in your
> private repository. Notice you only need to specify the name of the branch once
> then git will remember about it and you can push your new developments by
> simply doing `git push my-cmssw`.
**You need to PUSH YOUR changes** to make them available to others in your
private repository. Notice you only need to specify the name of the branch once
then git will remember about it and you can push your new developments by
simply doing `git push my-cmssw`.


### Do a pull request

> A **pull request** is a request to merge a given addition in your local repository
> to a branch in the official CMSSW repository. **Think of it as publishing a
> tagset in Tag Collector.** To start one click on the "Pull request" button which
> find on your personal repository.
A **pull request** is a request to merge a given addition in your local repository
to a branch in the official CMSSW repository. **Think of it as publishing a
tagset in Tag Collector.** To start one click on the "Pull request" button which
find on your personal repository.

![Pull request](images/pull-request.png)

### Select the topic branch which you want to propose and its target.

> The GUI for doing "Pull requests" looks like below:
The GUI for doing "Pull requests" looks like below:

![Pull request](images/pull-request-gui.png)

> If you click on the "Edit" button in the top right corner, you can select the
> "head branch" i.e. your addition on to of the official CMSSW.
If you click on the "Edit" button in the top right corner, you can select the
"head branch" i.e. your addition on to of the official CMSSW.

![Pull request](images/head-branch.png)

> Or change the "base branch", i.e. the one to which you want to have your changes merged.
Or change the "base branch", i.e. the one to which you want to have your changes merged.

![Pull requests GUI](images/base-branch.png)

> Remember to *write a sensible comment* just like you used to do for the
> publishing of tagsets and click on Send Pull Request.
Remember to *write a sensible comment* just like you used to do for the
publishing of tagsets and click on Send Pull Request.

### Go to the Topic Collector and check approval status

> Pull requests get automatically tracked in the [CMS Topic
> Collector][topic-collector], just like tagsets were tracked in the CMS topic
> collector.
Pull requests get automatically tracked in the [CMS Topic
Collector][topic-collector], just like tagsets were tracked in the CMS topic
collector.

![Topic Collector](images/topic-collector.png)

Expand Down

0 comments on commit fd128c3

Please sign in to comment.