|
Size: 5726
Comment:
|
Size: 3801
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #acl Known:read,write,admin,delete,revert |
#acl Known:write,read,delete,admin,revert All:read ### acl Known:read,write,admin,delete,revert |
| Line 6: | Line 6: |
| = Version control = | |
| Line 10: | Line 9: |
| The version control system [[http://subversion.tigris.org/|Subversion]] is installed on one of our servers. Currently, it is used for a number of research projects, some master's thesis projects and for the projects in the Project in Automatic Control course. If you would like to try out version control, talk to [[mailto:johan.akesson@control.lth.se|Johan Åkesson]] in order to have a repository for your files set up. | = Git = |
| Line 12: | Line 11: |
| == Guidelines for using Subversion == | [[http://http://git-scm.com/|Git]] is currently the preferred version control tool at the department. For starters you might want to look at a git tutorial I wrote some time ago [[attachment:git-tutorial.pdf]]. There are also heaps of tutorials out on the net. A quite comprehensive manual is [[http://www-cs-students.stanford.edu/~blynn/gitmagic/book.pdf| Git Magic]], another pretty good one is [[http://nyuccl.org/pages/GitTutorial/| Git for Scientists]]. It is also quite handy to have a [[attachment:git-cheat-sheet.svg|cheat sheet]] handy beside the keyboard for those quick command-and-options lookups. |
| Line 14: | Line 13: |
| An excellent source of knowledge about using Subversion can be found at [[http://svnbook.red-bean.com/]]. Here you will find basically everything you need (and more) to use Subversion efficiently. Some basic guidelines for using Subversion are: | Talk to [[mailto:anders.nilsson@control.lth.se|Anders Nilsson]] in order to have a repository for your files set up, or if you want to know more about version control. |
| Line 16: | Line 15: |
| * A typical Subversion repository has three directories at the top level: 'trunk', 'tags', and 'branches'. Development usually takes place in 'trunk', so all the project files should reside there. 'brances' are typically used to create snapshots of the trunk to enable concurrent development, and 'tags' are used to mark releases. See the Subversion book for more info. * Try to make atomic commits, meaning that each commit has a well defined scope. I several unrelated changes has been made to the code commit them separately. A good practice when using Subversion in association with trac is to always work with a particular ticket i mind. In this case, a commits are normally done in relation to tickets. * Be careful to use the log-message facility. This makes it much easier to trace the origin of code changes. If Subversion is used with trac, a reference to a ticket should normally be included in the log-message. Also, when a commit is made in relation to a ticket, it is useful to also add a reference to that commit in the trac ticket. |
== Setting up GIT == |
| Line 20: | Line 17: |
| == Project planning with Trac == In some larger, software-oriented projects involving several developers, it is useful to have a tool for planning, coordination, and documentation of the work. For this purpose, we now have the option to use [[http://trac.edgewall.org/|Trac]]. Trac is a web and wiki-based planning tool in which tickets/bugs can be registered and assigned to developers, milestones defined. Trac is also integrated with Subversion. |
You can run GIT locally on your machine. How to do this is covered [[http://git-scm.com/documentation|here]]. If you want a repo subsiding on one of the control servers, this is what to do: |
| Line 23: | Line 19: |
| The user's guide for Trac is integrated with the system itself. The following guidelines summarizes basic usage of Trac. | * Create an SSH key pair and send the public key to [[mailto:anders.nilsson@control.lth.se|Anders Nilsson]], mentioning that you want to use GIT. (First check that you don't already happen to have an SSH key pair, in which case creation is superfluous). Keys normally recide in {{{~/.ssh}}}. The private key is in {{{id_rsa}}}, while the public key is in {{{id_rsa.pub}}}. If you don't have these files, create them with the {{{ssh-keygen}}} command, described [[https://help.github.com/articles/generating-ssh-keys|here]]. |
| Line 25: | Line 21: |
| - Read the Trac documentation, and in particular the material related to wiki formatting and trac references. | * To create a repo, make sure you are on a computer with the correct ssh key and then, in the terminal, type: {{{ git clone ssh://gitolite@git.control.lth.se/user/repo }}} |
| Line 27: | Line 26: |
| - The name space for wiki-pages is global. Therefore, it is important to use a convention that does not introduce conflicts. Here we use the CamelCase (http://en.wikipedia.org/wiki/CamelCase) strategy for naming wiki pages in combination with name mangling where CamelCase names are concatenated and separated with slashes ('/') to create a hierarchical structure. For example, if the wiki page 'GuideLines' is created at the top level, a typical name of a sub-page is then 'GuideLines/Trac'. Notice that 'GuideLines/Trac' is considered by trac as a global name and not a hierarchical one. - Tickets typically follow a life cycle: - The ticket is created and a description is added. - The ticket is accepted by a developer that undertakes to perform the task specified in the ticket. - The ticket is resolved, usually by 'fixed'. There are also other options: - If a duplicate ticket is created, it can simply be resolved as 'duplicate'. This resolution is used also when a ticket is divided into two or more new tickets. Sometimes it is useful to create a very general ticket which is then divided into more specific ones. In such case, make sure that the new tickets refer back to the original ticket. - For some tickets it may be decided that the task will not be performed, for some reason. In this case, the ticket is resolved as 'wontfix'. - Make frequent use of cross-references between tickets, wiki pages and subversion revision numbers. In particular, it is important to add a reference from a ticket to a subversion commit whenever a commit is made relating to the particular ticket. Conversely, try to always add a reference to a ticket in subversion commit comments. This makes it much easier to search and trace the origin of code changes. Tickets are referred to using the syntax '#1', revisions by 'r1'. Please also see the trac documentation for more information on wiki formatting and trac references. - The 'component' field of a ticket is used to classify tickets and group them into different categories. Different projects typically have the need for different components and are accordingly created based on the specifics of the particular project. Since adding components requires admin privileges, please contact the trac administrator if new components need to be added. |
Replace {{{repo}}} with the desired repository name and {{{user}}} with your user name. The repo will be created on the server and cloned to the current directory on your machine. |
| Line 38: | Line 28: |
| * To see your server side repos, log into any fedora machine at the department and inspect {{{/home/repo/gitolite/repositories/user}}}, where {{{user}}} is your user name. If you want to delete repos from here, contact [[mailto:anders.nilsson@control.lth.se|Anders Nilsson]]. * To push changes to the remote server, first commit locally {{{git commit -m "This version is awesome."}}}, then push to the server {{{git push origin master}}}. = Subversion (deprecated) = The version control system [[http://subversion.tigris.org/|Subversion]] is installed on one of our servers. Currently, it is used for a number of research projects, some master's thesis projects and for the projects in the Project in Automatic Control course. However, since git reached maturity a couple of years ago there is very little reason in creating new subversion repositories unless you have good reasons to do so. SubversionTracGuidelines |
A version control system is useful when working on a collection of files that evolves over time, in particular if several people are modifying the files. For example, version control is often used in software projects to store the code in a way that several developers can access and contribute to the code without the need to send files by e-mail etc. Another example is when you are writing a paper with your colleagues and you need to efficiently and safely share your additions to the paper. A version control system also keeps track of the history of your contributions; most version control systems can be used to retrieve the state of your files as of a given date. This means that there is no need to create local back-up copies. To make it short and sweet: version control means you can relax.
Git
Git is currently the preferred version control tool at the department. For starters you might want to look at a git tutorial I wrote some time ago git-tutorial.pdf. There are also heaps of tutorials out on the net. A quite comprehensive manual is Git Magic, another pretty good one is Git for Scientists. It is also quite handy to have a cheat sheet handy beside the keyboard for those quick command-and-options lookups.
Talk to Anders Nilsson in order to have a repository for your files set up, or if you want to know more about version control.
Setting up GIT
You can run GIT locally on your machine. How to do this is covered here. If you want a repo subsiding on one of the control servers, this is what to do:
Create an SSH key pair and send the public key to Anders Nilsson, mentioning that you want to use GIT. (First check that you don't already happen to have an SSH key pair, in which case creation is superfluous). Keys normally recide in ~/.ssh. The private key is in id_rsa, while the public key is in id_rsa.pub. If you don't have these files, create them with the ssh-keygen command, described here.
- To create a repo, make sure you are on a computer with the correct ssh key and then, in the terminal, type:
git clone ssh://gitolite@git.control.lth.se/user/repo
Replace repo with the desired repository name and user with your user name. The repo will be created on the server and cloned to the current directory on your machine.
To see your server side repos, log into any fedora machine at the department and inspect /home/repo/gitolite/repositories/user, where user is your user name. If you want to delete repos from here, contact Anders Nilsson.
* To push changes to the remote server, first commit locally git commit -m "This version is awesome.", then push to the server git push origin master.
Subversion (deprecated)
The version control system Subversion is installed on one of our servers. Currently, it is used for a number of research projects, some master's thesis projects and for the projects in the Project in Automatic Control course. However, since git reached maturity a couple of years ago there is very little reason in creating new subversion repositories unless you have good reasons to do so.