|
Size: 5721
Comment:
|
Size: 3362
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #acl Known:read,write,admin,delete,revert ##Ask Leif if you don't know what the acl line means = Version control = |
#acl Known:write,read,delete,admin,revert All:read ### acl Known:read,write,admin,delete,revert |
| Line 10: | Line 6: |
| 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 8: |
| == 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 10: |
| 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 12: |
| * 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 14: |
| == 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: Go to [[gitlab.control.lth.se]], create a user, create a project, follow the instructions. |
| Line 23: | Line 16: |
| The user's guide for Trac is integrated with the system itself. The following guidelines summarizes basic usage of Trac. | * If you need to create an SSH key pair, instructions are found here: [[https://help.github.com/articles/generating-ssh-keys|here]]. |
| Line 25: | Line 18: |
| - Read the Trac documentation, and in particular the material related to wiki formatting and trac references. 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. |
* To push changes to the remote server, first commit locally {{{git commit -am "This version is awesome."}}}, then push to the server {{{git push}}}. Likewise you can pull changes from the server {{{git pull}}}. |
| Line 37: | Line 20: |
| * If you are annoyed by always having to type a message when you commiting: {{{ git config --global alias.co 'commit -a --allow-empty-message -m ""' git config --global alias.com 'commit -a --allow-empty-message' }}} * If you want to push each commit automatically, add the file {{{.git/hooks/post-commit}}} to the {{{.git}}} directory your repo. The file should contain: {{{ #!/bin/sh #!/bin/sh git push }}} * On OS X you might encounter annoying warnings like: {{{ perl: warning: Setting locale failed. perl: warning: Please check that your locale settings: LANGUAGE = (unset), LC_ALL = (unset), LC_CTYPE = "UTF-8", LANG = (unset) are supported and installed on your system. perl: warning: Falling back to the standard locale ("C"). }}} when communicating with the server. An easy fix to this is to avoid sending your locale settings to the server over SSH, by commenting out {{{SendEnv LANG LC_*}}} in {{{/etc/ssh_config}}} (sing a leading {{{#}}}). |
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: Go to gitlab.control.lth.se, create a user, create a project, follow the instructions.
If you need to create an SSH key pair, instructions are found here: here.
To push changes to the remote server, first commit locally git commit -am "This version is awesome.", then push to the server git push. Likewise you can pull changes from the server git pull.
- If you are annoyed by always having to type a message when you commiting:
git config --global alias.co 'commit -a --allow-empty-message -m ""' git config --global alias.com 'commit -a --allow-empty-message'
If you want to push each commit automatically, add the file .git/hooks/post-commit to the .git directory your repo. The file should contain:
#!/bin/sh git push
- On OS X you might encounter annoying warnings like:
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
LANGUAGE = (unset),
LC_ALL = (unset),
LC_CTYPE = "UTF-8",
LANG = (unset)
are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").when communicating with the server. An easy fix to this is to avoid sending your locale settings to the server over SSH, by commenting out SendEnv LANG LC_* in /etc/ssh_config (sing a leading #).