Difference between revisions of "Package Modification"

From SME Server
Jump to navigationJump to search
 
(21 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{Languages|:Package_Modification}}
 
{{Languages|:Package_Modification}}
===Introduction===
+
{{Level|Developer}}
SME Server code is stored in the CVS on http://www.sourceforge.net in two repositories:
 
* [http://fisheye1.cenqua.com/browse/smeserver/ CVS SME Server] which holds the core packages of the SME Server
 
* [http://fisheye1.cenqua.com/browse/smecontribs/ CVS SME Contribs] which holds the contribs packages
 
  
This page is to help you make changes to the contribs packages stored on sourceforge.
+
{{:SME_Server:Documentation:Developers_Manual:Chapter14}}
{{Note box|For now changes to the base are still made using mezzanine.}}
 
  
===Set up===
+
===Move contribs from SME(n-1) to SME(n) ===
====Local environment====
 
* We now use cvs without needing mezzanine, check you have it installed
 
yum install cvs
 
  
* Setup CVS to use ssh by creating /etc/profile.d/smebuild.sh with the following content
+
Here is an example for SME7 to SME8:
 
# Developer environment
 
# This gets symlinked into /etc/profile.d
 
 
export CVS_RSH=ssh # tell CVS to use ssh
 
 
# DO NOT set CVSROOT
 
 
alias rm='rm -i'
 
alias cp='cp -i --preserve=timestamps'
 
alias mv='mv -i'
 
You have to logout an login again to the console for changes to take effects.
 
 
 
====Access to build system====
 
Check updates/status on the build server: http://buildsys.contribs.org
 
 
 
{{Warning box|msg=For contrib builders using the plague-client-0.5.0 you will need to downgrade to  correct version, to fix this please do:
 
 
 
rpm -e plague-client plague-common
 
yum --enablerepo=smecontribs install plague-client}}
 
 
 
Ask admin@contribs.org for certificates, give the email address to use for notifications.
 
yum --enablerepo=smecontribs install plague-client
 
 
 
From now, do not use account "root" anymore. Use a dedicated dev account.
 
Copy certificates and config file to ~/
 
.plague-client.cfg
 
.username.pem
 
.contribs-upload-ca.pem
 
.contribs-server-ca.pem
 
 
 
Don't forget to set the proper privileges on the file
 
chmod 600 .username.pem
 
 
 
Check it's working
 
plague-client list_builders
 
 
Builders:
 
------------------------------------------------------------------------------------------
 
  build64-1.contribs.org      x86_64 amd64 ia32e noarch i386 i486 i586 i686 athlon available
 
  build32-1.contribs.org      i386 i486 i586 i686 athlon noarch  available
 
 
 
====Sourceforge access====
 
* SME Server code is stored in the CVS on  http://SourceForge.net. To be able to work on your code in the SME Server CVS repository you need an account on SourceForge. With this account the development team can give you access to the CVS repository. More information can be found here:
 
[http://sourceforge.net/docman/display_doc.php?docid=11123&group_id=1 B04: Registering a User Account]
 
[http://sourceforge.net/docman/display_doc.php?docid=29894&group_id=1 E04: CVS (Version Control for Source Code)]
 
[http://sourceforge.net/docs/F02/en/#top F02: SSH Key Generation and Usage]
 
 
 
* After you have created your SourceForge account you can ask the development team to give you developer access to smecontribs. Create a bug in the Bug Tracker as usual.
 
 
 
* Copy your local public SSH key to SourceForge https://sourceforge.net/account/editsshkeys.php 
 
 
 
* If local username is different to sf.net username edit ~/.ssh/config:
 
 
Host  smeserver.cvs.sourceforge.net
 
User  sfusername ''(without @shell.sf.net)''
 
Host  smecontribs.cvs.sourceforge.net
 
User  sfusername ''(without @shell.sf.net)''
 
 
 
* Don't forget to set the proper privileges on the file
 
 
chmod 600 ~/.ssh/config
 
  
===Usage===
+
'''Do a clean checkout of smeserver-mycontrib (This is very important, must be a completely clean tree)'''
====Import src.rpm====
+
rm -rf ~/smecontribs/rpms/smeserver-mycontrib
Email admin@contribs.org with the location of your rpm, it will be imported into the build system for you.
+
  cd ~/smecontribs/rpms
 
+
  cvs co smeserver-mycontrib
====Import cvs====
+
cd smeserver-mycontrib
This is just cvs information, not source code.
 
 
 
You can use ~/home/smeserver or whatever suits.
 
 
 
mkdir ~/smeserver
 
  cd ~/smeserver
 
  cvs -z3 -d:ext:smeserver.cvs.sourceforge.net:/cvsroot/smeserver co -P rpms
 
 
   
 
   
(for now changes to smeserver are still made with the mezzanine method, and updated manually by devs)
+
Then you can copy (DO NOT MODIFY ANYTHING before committing!!!):
 
+
cp -a contribs7 contribs8
  mkdir ~/smecontribs
+
  rm -rf contribs8/CVS
  cd ~/smecontribs
+
  cvs add contribs8
  cvs -z3 -d:ext:smecontribs.cvs.sourceforge.net:/cvsroot/smecontribs co -P rpms
+
  find contribs8 -mindepth 1 -name CVS -prune -o -print | xargs cvs add
 +
cvs commit -m 'Initial import'
 
   
 
   
To refresh run the following from the rpms directory, or any lower directory with a CVS dir
+
Finally you can make your first build
cvs update -dPA
 
 
 
====Modify a package====
 
Builders have rights to patch packages, tag, and build. 
 
If you need to upload new source tarballs or versions shad has to do that for now. Email them.
 
Binary files are stored in a look-aside cache on shads box. CVS isn't great on binary files.
 
 
 
Mezzanine, (mzsfget, mzclean, mzprep, mzpatch, mzbuild, mzput) have all be replaced with a new method.
 
 
 
Create a bug at http://bugs.contribs.org against your contrib
 
 
 
Change to work directory
 
cd smecontribs/rpms/smeserver-foo/contribs7
 
 
 
To prepare a tree
 
cvs update -dPA [optional]
 
make clean [optional]
 
make prep
 
  
=====Make a patch=====
+
  cd contribs8
Then switch to the tree and make modification.
+
  make local
 
 
Method A
 
 
 
In the prepared dir copy a file you want to modify like so:
 
 
 
  cp 28UserManagerProxyPass 28UserManagerProxyPass.{patchname}
 
 
 
Then modify the original file 28UserManagerProxyPass.
 
To add new files touch the file.{patchname} so it is empty.
 
 
 
Once you have all the files you want patched copied and changed then you can build the patch (from the contribs7 dir) with:
 
make patch SUFFIX={patchname}
 
It will build and add the patch for you.  It should be named "name-version-{patchname}.patch"
 
(man gendiff.  That is what the makefile uses to generate the diff file.)
 
 
 
Method B
 
 
 
Make a copy of the prepared directory, edit directly, then make a patch
 
 
 
cp smeserver-foo-1.0 smeserver-foo-1.0.old
 
diff -urN smeserver-foo-1.0.old smeserver-foo-1.0 > smeserver-foo-1.0-removeConfig.patch
 
 
 
=====Apply a patch=====
 
For example, check if a translation patch is available:
 
* for [http://translate.contribs.org/patches/ SME Server base]
 
* for [http://translate.contribs.org/patches/contribs/ SME Server contribs]
 
 
 
If patch size is 0 bytes there is nothing to do
 
 
 
Else go to the package folder in your tree and do :
 
 
 
wget http://translate.contribs.org/patches/contribs/{name}-locale-{date}.patch
 
cvs add {name}-locale-{date}.patch
 
 
 
Then you need to follow instructions in next part....
 
 
 
You may add yourself some [http://translate.contribs.org/ translations ], and wait for patch to be created (at about 2 AM  GMT-6, or 6 PM Sydney)
 
 
 
=====Edit the spec=====
 
nano -w smeserver-foo.spec
 
 
 
#increase the release
 
%define release 15
 
 
#add the patch
 
Patch2: smeserver-foo-1.2-widget.patch
 
 
#update the changelog, include the bug number
 
* Fri Jan 11 2008 John Smith <smith@foo.net> 1.2-15
 
- fixed foo to create bar [SME 3470]
 
 
#apply the patch in %setup
 
%patch2 -p1
 
 
 
=====Commit=====
 
Build the rpm locally to test, (note, this deletes the working tree!)
 
  make local      
 
 
 
Once you are satisfied and want to submit the package to the build server commit your changes. (Please use descriptive comments so that other developers are aware of what is happening.  Comments will appear on the subject line of the commit email that get send to the other developers.)
 
 
 
cvs commit -m 'your descriptive commit message here'
 
 
 
You can automate the addition of the comments in the spec file with the command 'clog'. {{Note box|You will need to be in the sme7, sme8, or contribs7 directory for this to work}}
 
 
 
rm -f clog
 
cvs commit -m "$(make clog)"
 
 
 
Then tag all files as belonging to a particular build version
 
 
  make tag
 
  make tag
 
Then submit the request to the build server which will checkout the recently tagged version and build it in a chroot (mock) env.
 
 
  make build
 
  make build
  
Key things are to always do "make tag" before "make build"
+
<noinclude>[[Category:SME9-Development]]
 
 
Always ensure you are working with the latest version (cvs update -dPA)
 
 
 
You and updatesteam will get an email on successfull build. 
 
Only you will get an email on failed build.
 
 
 
CVS cheat sheet [[:Package_Modification/More cvs commands]]
 
 
 
 
 
=====buildsys follow up =====
 
You can check the buidsys working thanks to plague: 
 
 
 
* [https://buildsys.contribs.org/plague https://buildsys.contribs.org/plague]
 
* or in shell
 
plague-client list uid  {task number}
 
 
 
You are notified by email of success or failure of your build request
 
 
 
====Releasing a package====
 
After the make build command the build system will try and build your package. After a successful build it will be put in the smetest repository. You should be notified of the result of the build by e-mail.
 
 
 
Once a package is build successfully you should verify your changes, ideally you would have a bug to verify for each modification. After verification of all relevant changes and bugs you can release the package like this:
 
<ol></li><li>Login to shell.contribs.org like this:
 
 
 
ssh username@shell.contribs.org
 
</li><li>Navigate to the teams directory:
 
 
 
cd /teams
 
</li><li>The teams directory contains a few directories of which two are relevant, the first is called updates which will hold the SME Server packages, the other is called contribs and will hold build contribs.
 
Suppose we would like to release our contrib we would proceed like this:
 
 
 
cd contribs/7
 
</li><li>Now copy the relevant package from smetest to smecontribs, old versions are removed automatically
 
 
 
cp smetest/package-name-version.rpm smecontribs/
 
</li></ol>
 
 
 
{{Note box|Within a period of two hours the package should be moved to the smecontribs repository and be available as soon as the mirrors synchronize.}}
 
 
 
===Workflow===
 
Once the server successfully builds it will automatically be pulled on the next repo update run
 
(40 past the even hours MDT). The package will either be put into the smedev (new package) or smetest (exist in higher repo)  After verification the package is manually moved from smedev/smetest to smecontribs (for contribs)  or smeupdates-testing (for packages in base)
 
 
 
===Mailing Lists===
 
Subscribe yourself to the [http://lists.contribs.org/mailman/listinfo/devinfo devinfo mailinglist]. This is the place to discuss the development of the server and contribs. If you have other questions, not regarding development please use the [http://forums.contribs.org forums].
 
 
 
Other lists exist to monitor bugs and the build system, UpdatesTeam + ...
 

Latest revision as of 21:33, 18 November 2018


PythonIcon.png Skill level: Developer
Risk of inconsistencies with Koozali SME Server methodology, upgrades & functionality is high. One must be knowledgeable about how changes impact their Koozali SME Server. Significant risk of irreversible harm.


The SME Server development environment

Configuring your development environment

The SME Server source code is checked into CVS at koozali.org. SME Server code is stored in the CVS on shell.koozali.org in two repositories:

Reminder: The SME Server source code is released under the GPL. You must release the source code to all modifications. If you make improvements, please raise a bug and attach a patch so the change can be discussed and pulled back into the base for everyone to share.

Only developers who are going to put patches back into CVS and build new packages need shell.koozali.org CVS access. The sources are freely available and patches are gratefully received. Just follow the instructions in this section and attach the patch(es) to the Bugzilla entry, explaining why the change should be made.


Local environment

  • Install cvs
yum install cvs rsh
  • Setup CVS to use ssh by creating /etc/profile.d/smebuild.sh with the following content
# Developer environment
# This gets symlinked into /etc/profile.d 

export CVS_RSH=ssh # tell CVS to use ssh

# DO NOT set CVSROOT

alias rm='rm -i'
alias cp='cp -i --preserve=timestamps'
alias mv='mv -i'

You have to logout and login again to the console for changes to take effects.

Access to build system

Check updates/status on the build server: http://buildsys.contribs.org


Warning.png Warning:
For contrib builders using the plague-client-0.5.0 you will need to downgrade to correct version, to fix this please do:
rpm -e plague-client plague-common
yum --enablerepo=smecontribs install plague-client

Ask admin@contribs.org for certificates, give the email address to use for notifications.

yum --enablerepo=smecontribs install plague-client

From now, do not use account "root" anymore. Use a dedicated dev account. Copy certificates and config file to ~/

.plague-client.cfg
.username.pem
.contribs-upload-ca.pem
.contribs-server-ca.pem

Don't forget to set the proper privileges on the file

chmod 600 .username.pem

Check it's working

plague-client list_builders

Builders:
------------------------------------------------------------------------------------------
 build64-1.contribs.org      x86_64 amd64 ia32e noarch i386 i486 i586 i686 athlon available
 build32-1.contribs.org      i386 i486 i586 i686 athlon noarch  available

CVS shell.koozali.org access

  • SME Server code is stored in the CVS on http://shell.koozali.org. To be able to work on your code in the SME Server CVS repository you need an account on Koozali.org. With this account the development team can give you access to the CVS repository.
  • After your Koozali.org account has been created you can ask the development team to give you developer access to smecontribs. Create a bug in the Bug Tracker as usual.
  • If local username is different to shell.koozali.org username edit ~/.ssh/config:
Host  shell.koozali.org
User  koozaliusername (without @shell.koozali.org)
port 222
  • Don't forget to set the proper privileges on the file
chmod 600 ~/.ssh/config

Import source to shell.koozali.org

Email admin@contribs.org with the location of your rpm, it will be imported into the build system for you. Follow the same procedure when an upstream release occurs, eg a new .tar.gz, Update your local cvs with:

cvs update -dPA

If you have developer access to buildsys you can follow this guide

https://wiki.contribs.org/Package_Import

Import cvs in your workspace

You can use ~/home/smeserver or whatever suits.

mkdir ~/home/smeserver
cd ~/home/smeserver
cvs -z3 -d:ext:shell.koozali.org:/cvs/smeserver co -P rpms 
mkdir ~/home/smecontribs
cd ~/home/smecontribs 
cvs -z3 -d:ext:shell.koozali.org:/cvs/smecontribs co -P rpms 

To refresh run the following from the rpms directory, or any lower directory with a CVS dir

cvs update -dPA

Modifying a SME Server package

Raise a Bugzilla entry

Before you make any changes to a package, you need to have a Bugzilla entry which specifies the problem and preferably proposes a fix. Raising the bug before you do the work allows others to comment on the proposed approach and can save significant time when you go to submit the changes. The change should also be approved by the Development Manager if it is meant for near-term release. You will need the Bugzilla bugid when you check in the changes.

All changes must have an associated Bugzilla entry. The bug tracker is here: http://bugs.contribs.org/

If a relevant bug does not exist, raise one. If the bug exists, assign it to yourself to show that you are working on it:

For this exercise, let's look at bug 1174 "yum-import-keys should not import duplicates" http://bugs.contribs.org/show_bug.cgi?id=1174.


Modify the package

If you are modifying an existing file, the simplest way to determine the package is to install the relevant version and run rpm -qf on the file to be modified:

[gordonr@smebuild actions]$ rpm -qf /etc/e-smith/events/actions/yum-import-keys
smeserver-yum-1.1.2-05

and so, we want to modify the smeserver-yum package.

All packages on the SME Server ISO/CD must be checked into shell.koozali.org CVS. The only exceptions are packages which come from the following upstream repositories: CentOS and dag.


You can now retrieve one of the packages from shell.koozali.org. In this case, we want to modify the smeserver-yum package, so let's retrieve it from shell.koozali.org:

cvs -z3 -d:ext:shell.koozali.org:/cvs/smeserver co -P smeserver-yum

Change to work directory

cd smeserver/rpms/smeserver-yum/sme7

To prepare a tree

cvs update -dPA   
make clean        
make prep
Make a patch

Then switch to the tree and make modification.

Method A

In the prepared dir copy a file you want to modify like so:

cp yum-import-keys yum-import-keys.{patchname}

Then modify the original file yum-import-keys. To add new files touch yum-import-keys.{patchname} so it is empty.

Once you have all the files you want patched copied and changed then you can build the patch (from the sme7 dir) with:

make patch SUFFIX={patchname}

It will build and add the patch for you. It should be named "name-version-{patchname}.patch". It will also add the patch to CVS.

Method B

Make a copy of the prepared directory, edit directly, then make a patch

cp -R smeserver-yum-2.0.0 smeserver-foo-2.0.0.old
diff -urN smeserver-foo-2.0.0.old smeserver-yum-2.0.0 > smeserver-yum-2.0.0-importKeys.patch
Apply a patch

For example, check if a translation patch is available:

If patch size is 0 bytes there is nothing to do

Else go to the package folder in your tree and do :

wget http://translate.contribs.org/patches/contribs/{name}-locale-{date}.patch
cvs add {name}-locale-{date}.patch

Then you need to follow instructions in next part....

You may add yourself some translations , and wait for patch to be created (at about 2 AM GMT-6, or 6 PM Sydney)

Edit the spec
nano -w smeserver-foo.spec
#increase the release
%define release 15

#add the patch
Patch2: smeserver-foo-1.2-widget.patch

#update the changelog, include the bug number
* Fri Jan 11 2008 John Smith <smith@foo.net> 1.2-15
- fixed foo to create bar [SME 3470]

#apply the patch in %setup
%patch2 -p1
Commit

Build the rpm locally to test, (note, this deletes the working tree!)

make local       

Once you are satisfied and want to submit the package to the build server commit your changes. (Please use descriptive comments so that other developers are aware of what is happening. Comments will appear on the subject line of the commit email that get send to the other developers.)

cvs commit -m 'your descriptive commit message here'

You can automate the addition of the comments in the spec file with the command 'clog'.

Important.png Note:
You will need to be in the sme7, sme8, or contribs7 directory for this to work

rm -f clog
cvs commit -m "$(make clog)"

CVS cheat sheet Package_Modification/More cvs commands

Build

Tag all files as belonging to a particular build version

make tag

Submit the request to the build server which will checkout the recently tagged version and build it

make build

Always do "make tag" before "make build"

Always ensure you are working with the latest version (cvs update -dPA)

You and updatesteam will get an email on successful build. Only you will get an email on failed build.

You can check the build system is working:

plague-client list uid  {task number}

Releasing a contrib package

After the make build command the build system will try and build your package. After a successful build it will be put in the smetest repository. You should be notified of the result of the build by e-mail.

Once a package is build successfully you should verify your changes, ideally you would have a bug to verify for each modification. After verification of all relevant changes and bugs you can release the package like this:

  1. Login to shell.contribs.org like this: ssh -p222 username@shell.koozali.org
  2. Navigate to the smeserver directory: cd /teams/smeserver
  3. The teams directory contains a few directories of which two are relevant, the first is called updates which will hold the SME Server packages, the other is called contribs and will hold build contribs. Suppose we would like to release our contrib we would proceed like this: cd contribs/9
  4. Now copy the relevant package from smetest to smecontribs, old versions are removed automatically cp smetest/package-name-version.rpm smecontribs/


Important.png Note:
Within a period of one hour the package should be moved to the smecontribs repository and be available as soon as the mirrors synchronize.

Once the server successfully builds it will automatically be pulled on the next repo update run (40 past the even hours MDT). The package will either be put into the smedev (new package) or smetest (exist in higher repo) After verification the package is manually moved from smedev/smetest to smecontribs (for contribs) or smeupdates-testing (for packages in base)

Mailing Lists

Subscribe yourself to the devinfo mailinglist. This is the place to discuss the development of the server and contribs. If you have other questions, not regarding development please use the forums.

Move contribs from SME(n-1) to SME(n)

Here is an example for SME7 to SME8:

Do a clean checkout of smeserver-mycontrib (This is very important, must be a completely clean tree)

rm -rf ~/smecontribs/rpms/smeserver-mycontrib
cd ~/smecontribs/rpms
cvs co smeserver-mycontrib
cd smeserver-mycontrib

Then you can copy (DO NOT MODIFY ANYTHING before committing!!!):

cp -a contribs7 contribs8
rm -rf contribs8/CVS
cvs add contribs8
find contribs8 -mindepth 1 -name CVS -prune -o -print | xargs cvs add
cvs commit -m 'Initial import'

Finally you can make your first build

cd contribs8
make local
make tag
make build