CVS Workshop. How to manage your projects, source code, and associated files using the Concurrent Versioning System

Transcription

1 CVS Workshop How to manage your projects, source code, and associated files using the Concurrent Versioning System 1

2 Purpose CVS is the most commonly used Open Source Version Management System. We need to backup, maintain and manage the objects used to develop projects as well as the ability to track changes through past versions. We need to have a consistently implemented multi-platform source repository for all source for each system. 2

3 Key Definitions CVS the Concurrent Versioning System, is a version control system generally used as part of the software development cycle to track and co-ordinate source code changes among a team of developers. Project A collection of programs, scripts, data files, documentation, and other associated objects which together address a single function or subsystem as defined by the Project Team. They must decide on the granularity. Module Often confused with Project, but in CVS terms, a commonly defined object used by multiple Projects. Sandbox - CVS has a unique method of working from most other version control systems in that developers can edit the same files concurrently. This is done by checking out a version of the project from the repository into a local directory on your computer. This local copy is called a sandbox. 3

4 MVS vs UNIX Environments The Life of a Modification MVS/IMS Environment 1. userid.ee123.project() 2. Restore source userid.ee123.cobol userid.ee123.cntl userid.load(ee123) 3. a0011.dp.t901d(ee123) 4. imsvs.temppgm(ee123) 5. imsvs.pgmlib(ee123) 6. Backup source to PDP Delete userid.ee123.cobol UNIX/Web Environment 1. $HOME/sandbox/ee123/ 2. cvs checkout ee123 ee123.c ee123.test.sh ee123 (executable) 3. /priv/adminsys/wwwdevl/ htdocs/webapp/ee/ee_app /ee /priv/adminsys/wwwprom ote/htdocs/webapp/ee/ee_ app/ee /priv/adminsys/wwwprod/ htdocs/webapp/ee/ee_app /ee cvs commit 7. cvs release -d ee123 4

5 Using CVS in the UNIX Environment 5

6 CVS Creating a Project As an example, let's create a new project consisting of a shell script and a Perl script that announce themselves to the world. You first need to create a directory to hold all of the files required for the project. One idea is to have a directory called newproject inside your sandbox directory. Create the two files ee_hello_world and ee_hello_world.pl in the directory. A quick way to do this is to copy the two example files from /priv/adminsys/courses/introduction-to-unix/samplefiles. Edit and modify the files to add your own personal information. To avoid clobbering your neighbour, rename the scripts to ee_xxx_hello_world where xxx is your userid. Note the CVS keywords $Id, $Source, $Log. CVS will manage these provided you enter them in a comment area. 6

7 CVS - Importing a Project Now that you have your files ready, you can import your project into the CVS repository. Note there can be as many repositories as we require. At this point, we define one per System ID. For this course however, you must use the course repository. You must set the environment variable CVSROOT= /priv/adminsys/courses/introduction-tounix/cvs and export it via export CVSROOT. Inside the your newproject directory, you can now issue the cvs import command: cvs import ee_xxx_hello_world V R again xxx is your userid. V and R are used by import for release names. Provided you did not get any error messages, your project files are now entered into the CVS repository. You can now delete the files in your newproject directory. 7

8 CVS - Import Example <alders@chara:218>$ pwd /home/u1/alders/sandbox/newproject <alders@chara:219>$ ls -l total 16 -rwxrwx--- 1 alders adpcat 1028 Jul 2 11:17 ee_alders_hello_world -rwxrwx--- 1 alders adpcat 583 Jul 2 11:17 ee_alders_hello_world.pl <alders@chara:220>$ CVSROOT="/priv/adminsys/courses/introduction-tounix/cvs" <alders@chara:221>$ export CVSROOT <alders@chara:222>$ cvs import ee_alders_hello_world V R (You will be asked to enter comments about the changes made. Enter them and save) N ee_alders_hello_world/ee_alders_hello_world N ee_alders_hello_world/ee_alders_hello_world.pl No conflicts created by this import 8

9 CVS - Checking Out a Project You are now ready to checkout the project from the repository to make changes and work on it. This is done via cvs checkout Change your directory to your ~/sandbox and then run the command cvs checkout ee_$user_hello_world Note the directory ~/sandbox/ee_xxx_hello_world has been created and it will contain two files that you previously imported. Edit the files and see what CVS has done the the CVS comments. You can now make any changes required, test your changes, etc. 9

10 CVS - Checkout Example <alders@chara:247>$ cd ~/sandbox <alders@chara:248>$ pwd /home/u1/alders/sandbox <alders@chara:249>$ echo $CVSROOT /priv/adminsys/courses/introduction-to-unix/cvs <alders@chara:250>$ cvs checkout ee_alders_hello_world cvs checkout: Updating ee_alders_hello_world U ee_alders_hello_world/ee_alders_hello_world U ee_alders_hello_world/ee_alders_hello_world.pl <alders@chara:251>$ ls -l ee_alders_hello_world total 24 drwxrws--- 2 alders adpcat 4096 Jul 2 13:23 CVS -rwxrwxr-x 1 alders adpcat 1279 Jul 2 13:07 ee_alders_hello_world -rwxrwxr-x 1 alders adpcat 843 Jul 2 13:07 ee_alders_hello_world.pl 10

11 CVS - Committing Changes Once you have finished making changes to the project and have tested them, you are ready to commit your changes to the repository In our example, edit the two files to make some minor changes. Test them to make sure you are happy that the changes work. Ensure that you are located in the project sandbox directory. Ensure that CVSROOT points to the correct repository. Run cvs commit to commit your changes. Note, if you have a one-line change comment that is common to all of your files, you can specify this using the -m command line option. Be sure to enclose the text in. 11

12 CVS - Commit Example <alders@chara:281>$ echo $CVSROOT /priv/adminsys/courses/introduction-to-unix/cvs <alders@chara:282>$ pwd /home/u1/alders/sandbox/ee_alders_hello_world <alders@chara:283>$ cvs commit -m "Make production ready" cvs commit: Examining. Checking in ee_alders_hello_world; /priv/adminsys/courses/introduction-tounix/cvs/ee_alders_hello_world/ee_alders_hello_world,v <-- ee_alders_hello_world new revision: 1.2; previous revision: 1.1 done Checking in ee_alders_hello_world.pl; /priv/adminsys/courses/introduction-tounix/cvs/ee_alders_hello_world/ee_alders_hello_world.pl,v <-- ee_alders_hello_world.pl new revision: 1.2; previous revision: 1.1 done 12

13 CVS - Add/Remove Files Throughout the life of a project, other files will need to be added to the repository such as test data, test scripts, documentation, etc. These are added to the project using the cvs add command. To add a file or directory, locate to the project directory where the file or directory already exists and run cvs add file1 file2... Conversely, over time files will no longer be required and can be deleted from the project. This is done with cvs remove. You must first delete the files or directories physically and then run the command: cvs remove file1 file2... CVS will schedule addition or removal of file on the next commit. Note, files that are removed are actually stored away in the project's attic in case they are ever needed again. 13

14 CVS - Add/Remove Example <alders:286>$ cvs add ee_alders_hello_world.txt \ ee_alders_hello_world log cvs add: scheduling file `ee_alders_hello_world.txt' for addition cvs add: scheduling file `ee_alders_hello_world log' for addition cvs add: use 'cvs commit' to add these files permanently <alders:287>$ rm ee_alders_hello_world log rm: remove ee_alders_hello_world log (yes/no)? y <alders:288>$ cvs remove ee_alders_hello_world log cvs remove: removed `ee_alders_hello_world log' <alders:289>$ cvs commit -m Add documentation files to project cvs commit: Examining. RCS file: /priv/adminsys/courses/introduction-tounix/cvs/ee_alders_hello_world/ee_alders_hello_world.txt,v done Checking in ee_alders_hello_world.txt; /priv/adminsys/courses/introduction-tounix/cvs/ee_alders_hello_world/ee_alders_hello_world.txt,v <-- ee_alders_hello_world.txt initial revision: 1.1 done 14

15 CVS - Project Deployment In today's environment of primarily scripting language, it is tempting to change the component's source where it is run from. It is essential that all changes done to a project's components be done inside the CVS sandbox directories. In order to manage the changes, CVS needs to know that the source code it has is the only set being changed. To ease this synchronization, CVS has an export command, which will export only the project files into a named directory. This does not export the CVS internal files. It can also deploy only a specific release or released date. To run the command for the most current release committed, execute cvs export -d targetdirectory -D now projectname 15

16 CVS - Export Example <alders@chara:314>$ cvs export -D now \ -d /home/adpc/cservap/ee/app/ee_alders_hello_world \ ee_alders_hello_world cvs export: Updating /home/adpc/cservap/ee/app/ee_alders_hello_world U /home/adpc/cservap/ee/app/ee_alders_hello_world/ee_alders_hello_world U /home/adpc/cservap/ee/app/ee_alders_hello_world/ee_alders_hello_world.pl U /home/adpc/cservap/ee/app/ee_alders_hello_world/ee_alders_hello_world.txt <alders@chara:315>$ ls -l \ /home/adpc/cservap/ee/app/ee_alders_hello_world total 24 -rwxrwxr-x 1 alders cservap 1362 Jul 2 15:13 ee_alders_hello_world -rwxrwxr-x 1 alders cservap 933 Jul 2 15:13 ee_alders_hello_world.pl -rw-rw-r-- 1 alders cservap 497 Jul 2 15:31 ee_alders_hello_world.txt 16

17 CVS - Cleaning Up Of course once you have committed all of your changes and are satisfied that everything is working correctly in production, you should clean up your sandbox. This is not mandatory, but always a best practice to make sure that you do not exceed your disk space quota, as well as to make sure that you have closed your checkout and have freed up any locks. Make sure to position yourself to your ~/sandbox directory, ie. One level above the project. Run the command cvs release -d projectname This will delete the files and directories belonging to the project and remove your userid from checkout status in the repository. 17

18 CVS - Release Example <alders@chara:303>$ ls afauthentication ee_alders_hello_world dc_generate_parms ee_perl_examples dc_job hr_umfa dd_operational_documentation hr_vipdaemons dp_check_cronlog newproject dp_errorlog or dp_rotate rsvalpin dp_services xxx <alders@chara:304>$ pwd /home/u1/alders/sandbox <alders@chara:305>$ cvs release -d ee_alders_hello_world You have [0] altered files in this repository. Are you sure you want to release (and delete) directory `ee_alders_hello_world': y <alders@chara:306>$ ls -ld ee_alders_hello_world ee_alders_hello_world: No such file or directory 18

19 CVS - Beyond Simple Projects CVS is the most commonly used source management tool in the industry. It is commonly used to manage open source projects with developers working on joint projects worldwide. CVS can define modules which are made up of components from different projects. Hence a module can share and reuse components across many projects. Further research needs to be done locally to establish best practices on how we accomplish this. Stay tuned. CVS will become the basis to production change control and change management of projects being promoted into various environments, such as production and training. Admin Systems will move System based CVS repositories on to a remote CVS server to provide better access and security from all platforms. EG. Windows, UNIX, Linux, MacIntosh, Web, etc. 19

20 CVS - Best Practices We are still gaining experience with CVS. It is a very powerful product with many options. Expect a great many best practices to come in the near future as people gain experience with it. The discipline of making changes only to project components within a CVS sandbox and then exporting the changes into executable directories is critical to success. Only use cvs export or cp project files into their executable environments. Never make changes to components in these directories directly. CVS is not a substitute for good project management. Project leads need to actively ensure that project staff get assigned to projects where overlapping work is avoided or controlled. CVS will attempt to resolve concurrent changes to project files, however, good definition and granularity decisions for the projects is critical. 20

21 Using CVS in the Windows Environment Using TortoiseCVS 21

22 Checking out a Module Using Windows Explorer, right-click on C:\Sandbox and select CVS Checkout: Protocol should be set to Password server [:pserver:] Server should be set to chara.cc.umanitoba.ca Repository folder: to your system s repository User name: your userid Module if you know it or press Fetch list to populate the pulldown. Click OK to Checkout the Project. 22

23 Creating a Project To create a new project, create a folder under C:\Sandbox using the name of the project. In this case I used ee_course_test Right click on the new folder and select CVS then Make New Module 23

24 CVS - Add/Remove Example After you have created the project files in the new project directory, right click on the directory name and select CVS Add Contents The file icons will change to show they are now a part of the project. 24

25 Adding/Removing Files Later To remove or add files individually, select the file by clicking on it and then right click the file and select either CVS Add or CVS then - Remove and click OK. Notice that the file icon will change to reflect its new status. 25

26 Committing the Project When you are ready to commit your project into the repository, right click on the project s directory icon and select CVS Commit Enter comments explaining the changes you may have done and click OK. 26

27 Cleaning Up After you have committed your project, you should now cleanup your sandbox. To do this, right click on the project directory and select CVS then Release You can now click ok and the directory will be deleted. Note if any files were not added to the project, the directory will remain with those files in it and you will then need to manually delete them. 27

28 Using CVS in the Web Environment Using CVSWEB 28

29 Selecting Repositories and Projects By selecting Application Technologies from the pulldown, and then selecting ee_course_test, you can now view the project we had entered in the above examples. 29

30 Accessing CVSWEB We have installed a CVS web repository viewer known as CVSWEB. oba.ca/webapp/at/cvswe b If any new repositories are created, inform Application Technologies to set them up Security is setup based on ip address and userid/password control. Userids need to be added by Application Technologies. 30

31 Viewing Project Objects Individual Objects in each projects can be viewed in a number of ways. Shown here is the historical summary The following slides will shown the various detailed views. 31

32 Viewing Object as Text By selecting the Text view you will be presented with a simple ASCII text page showing the source code of the object. 32

33 Viewing Object as Markup By selecting the Markup view you will be presented with a header containing summary information followed by a text page showing the source code of the object. 33

34 Viewing Object as Annoted By selecting the Annoted view you will be presented with a text page showing the source code of the object. In the left margin there are indicators showing in which revision changes occurred. 34

35 Viewing Object as Select for Diffs By selecting the Select for Diffs view you will first be presented with a seclection page to choose which version to compare. Next by selecting Preferred you will be presented with a colour coded page showing the source code of the object. The left side will be the previous selected version and the right the newer version. 35

36 References There are several documents found in S:\Adminsys\DOCS\CVS. The official site for CVS can be found at TortoiseCVS has an excellent on-line help file. There are portion still under construction however. Also see 36