Contribute/First Steps with your KDE SVN Account: Difference between revisions

    From KDE TechBase
    (→‎Notations: minor grammar change & attempt at clarity by using parallel structure for "KDE's anon and nonanon")
    (no need for username now)
    (9 intermediate revisions by 7 users not shown)
    Line 1: Line 1:
    {{warning|This page is yet to be reviewed for changes required by the migration to Git.  Information and commands on this page may no longer be valid and should be used with care. Please see the [[Development/Git|KDE Git hub page]] for more details. }}
    {{improve}}
    {{improve}}
    This tutorial is about what to do when you are a fresh owner of a new SVN account for KDE.
    This tutorial is about what to do when you are a fresh owner of a new contributor account for KDE.


    == Notations ==
    == Notations ==
    * ''SVN'' is used to describe an SVN server, mostly KDE's non-anonymous or anonymous SVN servers.
    * ''SVN'' is used to describe an SVN server, mostly KDE's non-anonymous or anonymous SVN servers.
    * The lower case word ''svn'' is used to describe the program named svn, which the user can use to access SVN.
    * The lower case word ''svn'' is used to describe the program named svn, which the user can use to access SVN.
    * By ''username'' the name of your KDE SVN account is meant (also known as ''login'').


    == Preliminary ==
    == Preliminary ==


    This tutorial assumes that you have [[Contribute/Get a SVN Account|applied for a KDE SVN account as described here]] and that you have received a positive answer with the information associated with your new account.
    This tutorial assumes that you have [[Contribute/Get a Contributor Account|applied for a KDE Contributor account as described here]] and that you have received a positive answer with the information associated with your new account.


    == Read First! ==
    == Read First! ==


    Now you have a KDE SVN account.
    Now you have a KDE Contributor account.


    Please note that the answer email will have an explanation about how to use the account. (This explanation is also the file [http://websvn.kde.org/trunk/kde-common/svn/svn_instructions.txt?view=markup kde-common/svn/svn_instructions.txt].) It contains also topics not discussed here. So please read this email.
    Please note that the answer email will have an explanation about how to use the account. (This explanation is also the file [http://websvn.kde.org/trunk/kde-common/svn/svn_instructions.txt?view=markup kde-common/svn/svn_instructions.txt].) It contains also topics not discussed here. So please read this email.
    Line 21: Line 22:
    == Changed URLs ==
    == Changed URLs ==


    Until now, you have worked with one of the anonymous SVN servers. Now that you have a KDE SVN account, you will not use that anonymous server anymore. Therefore the base URL to the SVN server changes for you.
    Until now, you have worked with one of the anonymous servers. Now that you have a KDE Contributor account, you will not use that anonymous server anymore. Therefore the base URL to the SVN server changes for you.


    For the standard anonymous SVN of KDE, it was: {{path|svn://anonsvn.kde.org}} assuming that you have not used an anonymous SVN mirror. If you have used another anonymous SVN server for KDE, then please use its URL instead.
    For the standard anonymous SVN of KDE, it was: {{path|svn://anonsvn.kde.org}} assuming that you have not used an anonymous SVN mirror. If you have used another anonymous SVN server for KDE, then please use its URL instead.
    Line 27: Line 28:
    {{Note|If you are unsure which SVN anonymous server you have used, use the <tt>svn info</tt> command to get the server URL.}}
    {{Note|If you are unsure which SVN anonymous server you have used, use the <tt>svn info</tt> command to get the server URL.}}


    Now the new base URL for your access to the KDE SVN server depends on which way you have chosen to access it:
    Now the new base URL for your access to the KDE SVN server will be:
    * by HTTPS, it becomes:
      svn+ssh://svn@svn.kde.org/home/kde
    <nowiki>https://[email protected]/home/kde</nowiki>
    There is no need to specify a username, the server will work that out from your ssh key
    * by SSH, it becomes
      svn+ssh://username@svn.kde.org/home/kde
    where <tt>username</tt> is the name that was given to your KDE SVN account.


    == Changing The URLs of the Modules of Your Local SVN Copy ==
    == Changing The URLs of the Modules of Your Local SVN Copy ==
    Line 41: Line 39:


    Assuming that you are processing the kdelibs module, you have to use:
    Assuming that you are processing the kdelibs module, you have to use:
    * for HTTPS
      svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://svn@svn.kde.org/home/kde/trunk/KDE/kdelibs
    svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs https://svn.kde.org/home/kde/trunk/KDE/kdelibs --username yourname
    * for SSH:
      svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://username@svn.kde.org/home/kde/trunk/KDE/kdelibs


    For other modules than kdelibs (or for branches or for tags), you have to change the relative module path; similarly, if you used another anonymous server.
    For other modules than kdelibs (or for branches or for tags), you have to change the relative module path; similarly, if you used another anonymous server.
    Line 50: Line 45:
    Be careful on what URLs you type, as SVN will only replace the exact old URL by the exact new URL. So if you mistype one of the URLs, it will not work later. (If you have already fallen into this pitfall, it is not a problem, just use relocate again to replace the wrong URL with the right one.)
    Be careful on what URLs you type, as SVN will only replace the exact old URL by the exact new URL. So if you mistype one of the URLs, it will not work later. (If you have already fallen into this pitfall, it is not a problem, just use relocate again to replace the wrong URL with the right one.)


    If you connect by HTTPS, as the first relocation will be the first contact to the KDE SVN server with your new SVN account, you will be asked to confirm the SSL certificate of the server and then you will be asked to authenticate yourself.
    You will be asked to accept the SSL certificate on the first attempt to access the server.


    If connecting with svn+ssh, you will be asked to accept the SSL certificate on the first attempt to access the server.
    <syntaxhighlight lang="bash">
     
    $ svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://svn@svn.kde.org/home/kde/trunk/KDE/kdelibs
    <code>
    $ svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://username@svn.kde.org/home/kde/trunk/KDE/kdelibs
    The authenticity of host 'svn.kde.org (195.135.221.74)' can't be established.
    The authenticity of host 'svn.kde.org (195.135.221.74)' can't be established.
    RSA key fingerprint is 86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb.
    RSA key fingerprint is 86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb.
    Are you sure you want to continue connecting (yes/no)? yes
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added 'svn.kde.org,195.135.221.74' (RSA) to the list of known hosts.
    Warning: Permanently added 'svn.kde.org,195.135.221.74' (RSA) to the list of known hosts.
    </code>
    </syntaxhighlight>


    Ensure that the fingerprint matches that in the document [http://developer.kde.org/documentation/tutorials/subversion/#structure Using Subversion with KDE]. (Normally, the SHA1 fingerprint is used for HTTPS.)
    Ensure that the fingerprint matches that in the document [http://techbase.kde.org/Getting_Started/Sources/Using_Subversion_with_KDE#The_KDE_repository_structure Using Subversion with KDE]. (Normally, the SHA1 fingerprint is used for HTTPS.)
     
    A quick troubleshooting note: if you cannot access the server with your new account made for accessing by HTTPS, you can try to give the HTTPS path in Konqueror. You will not be able to do much with Konqueror, but at least you must be able to login. That helps to know if the problem is more the server or your account or if the problem is svn. If you cannot login at all and you cannot find why, ask the [mailto:[email protected] Sysadmins] for help.


    == First Test ==
    == First Test ==
    Line 70: Line 61:
    The following steps are described using the command line tool <tt>svn</tt>. Personally, I find it better to start with it, as you know immediately where the problems are. Of course, after you have made your first test, you may use whatever tool that you prefer.
    The following steps are described using the command line tool <tt>svn</tt>. Personally, I find it better to start with it, as you know immediately where the problems are. Of course, after you have made your first test, you may use whatever tool that you prefer.


    Then you should be ready to start. The best test is to try to update a small directory. So change to a (small) directory of your local copy of KDE and type: <code bash>svn update</code>
    Then you should be ready to start. The best test is to try to update a small directory. So change to a (small) directory of your local copy of KDE and type: <syntaxhighlight lang="bash">svn update</syntaxhighlight>


    Alternatively, if you have no local copies installed, you can just checkout a module.
    Alternatively, if you have no local copies installed, you can just checkout a module.
    <code bash>svn checkout YOUR_URL</code>
    <syntaxhighlight lang="bash">svn checkout YOUR_URL</syntaxhighlight>
    Obviously, replace YOUR_URL with the correct path.
    Obviously, replace YOUR_URL with the correct path.


    Line 79: Line 70:


    {{note|If you know CVS, you will perhaps wonder that there is no <tt>cvs login</tt>, Subversion has chosen not to have such a way to login. The login is done at the first connection, where authentication is needed.}}
    {{note|If you know CVS, you will perhaps wonder that there is no <tt>cvs login</tt>, Subversion has chosen not to have such a way to login. The login is done at the first connection, where authentication is needed.}}
    == SVN Account Password ==
    This section is only for accessing KDE SVN by HTTPS, so skip this if you use SSH. For SSH, it is SSH that secures the connection, so normal SSH habits and procedures apply.
    The password is automatically transmitted to the SVN server by each use of the SVN program when accessing by HTTPS.
    ''Please note:'' the password is stored somewhere in the directory {{path|~/.subversion/auth}}. So please check that these files cannot be read by third persons, as the password is '''unencoded'''.
    In case that someone has gained access to your password (or if you have a doubt) please email [mailto:[email protected] KDE's Sysadmins] to change your password or at least to get it disabled temporarily.


    == Default Editor ==
    == Default Editor ==
    Line 102: Line 83:


    So maybe you should check your environment variables:
    So maybe you should check your environment variables:
    <code bash>
    <syntaxhighlight lang="bash">
    echo $SVN_EDITOR
    echo $SVN_EDITOR
    echo $VISUAL
    echo $VISUAL
    echo $EDITOR
    echo $EDITOR
    </code>
    </syntaxhighlight>


    Check that their settings suit you for your work with svn. If they do not suit you, check your file {{path|~/.bashrc}} and add something like:
    Check that their settings suit you for your work with svn. If they do not suit you, check your file {{path|~/.bashrc}} and add something like:
    <code bash>export SVN_EDITOR=mcedit</code>
    <syntaxhighlight lang="bash">export SVN_EDITOR=mcedit</syntaxhighlight>
    Here it sets mcedit, replace it with your favorite editor. Of course you can set <tt>$EDITOR</tt> instead if you want to change the default editor for you.
    Here it sets mcedit, replace it with your favorite editor. Of course you can set <tt>$EDITOR</tt> instead if you want to change the default editor for you.


    Line 135: Line 116:


    The digest features a small statistics section. To improve the accuracy of those, you should add some information, like age or country, about yourself, which you can do [http://commit-digest.org/data here].
    The digest features a small statistics section. To improve the accuracy of those, you should add some information, like age or country, about yourself, which you can do [http://commit-digest.org/data here].
    == Commit-Filter ==
    [http://commitfilter.kde.org/ Commit-Filter] is a service which allows you to monitor folders (or authors) in SVN for changes, and have each commit's diff emailed to you. This is very useful if you are interested in getting involved in a certain sub-project of KDE and want to keep up with its development.
    Please use reply-to-all when responding to those emails.


    == Links ==
    == Links ==

    Revision as of 13:46, 4 November 2013

    Warning
    This page is yet to be reviewed for changes required by the migration to Git. Information and commands on this page may no longer be valid and should be used with care. Please see the KDE Git hub page for more details.


    Warning
    This section needs improvements: Please help us to

    cleanup confusing sections and fix sections which contain a todo


    This tutorial is about what to do when you are a fresh owner of a new contributor account for KDE.

    Notations

    • SVN is used to describe an SVN server, mostly KDE's non-anonymous or anonymous SVN servers.
    • The lower case word svn is used to describe the program named svn, which the user can use to access SVN.

    Preliminary

    This tutorial assumes that you have applied for a KDE Contributor account as described here and that you have received a positive answer with the information associated with your new account.

    Read First!

    Now you have a KDE Contributor account.

    Please note that the answer email will have an explanation about how to use the account. (This explanation is also the file kde-common/svn/svn_instructions.txt.) It contains also topics not discussed here. So please read this email.

    In case of conflicting instructions, please follow those of the email, not the ones of this tutorial.

    Changed URLs

    Until now, you have worked with one of the anonymous servers. Now that you have a KDE Contributor account, you will not use that anonymous server anymore. Therefore the base URL to the SVN server changes for you.

    For the standard anonymous SVN of KDE, it was: svn://anonsvn.kde.org assuming that you have not used an anonymous SVN mirror. If you have used another anonymous SVN server for KDE, then please use its URL instead.

    Note
    If you are unsure which SVN anonymous server you have used, use the svn info command to get the server URL.


    Now the new base URL for your access to the KDE SVN server will be:

    svn+ssh://[email protected]/home/kde
    

    There is no need to specify a username, the server will work that out from your ssh key

    Changing The URLs of the Modules of Your Local SVN Copy

    This only applies if you have local copies of SVN files that were taken from an anonymous SVN Server, otherwise skip this.

    To use the KDE SVN server instead of one of the anonymous SVN servers, you need to tell each module of your local SVN copy that you want to change the server. SVN does this with the command

    svn switch --relocate
    

    Assuming that you are processing the kdelibs module, you have to use:

    svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://[email protected]/home/kde/trunk/KDE/kdelibs
    

    For other modules than kdelibs (or for branches or for tags), you have to change the relative module path; similarly, if you used another anonymous server.

    Be careful on what URLs you type, as SVN will only replace the exact old URL by the exact new URL. So if you mistype one of the URLs, it will not work later. (If you have already fallen into this pitfall, it is not a problem, just use relocate again to replace the wrong URL with the right one.)

    You will be asked to accept the SSL certificate on the first attempt to access the server.

    $ svn switch --relocate svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs svn+ssh://[email protected]/home/kde/trunk/KDE/kdelibs
    The authenticity of host 'svn.kde.org (195.135.221.74)' can't be established.
    RSA key fingerprint is 86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added 'svn.kde.org,195.135.221.74' (RSA) to the list of known hosts.
    

    Ensure that the fingerprint matches that in the document Using Subversion with KDE. (Normally, the SHA1 fingerprint is used for HTTPS.)

    First Test

    The following steps are described using the command line tool svn. Personally, I find it better to start with it, as you know immediately where the problems are. Of course, after you have made your first test, you may use whatever tool that you prefer.

    Then you should be ready to start. The best test is to try to update a small directory. So change to a (small) directory of your local copy of KDE and type:

    svn update
    

    Alternatively, if you have no local copies installed, you can just checkout a module.

    svn checkout YOUR_URL
    

    Obviously, replace YOUR_URL with the correct path.

    Now you can use the SVN commands on KDE's main SVN.

    Note
    If you know CVS, you will perhaps wonder that there is no cvs login, Subversion has chosen not to have such a way to login. The login is done at the first connection, where authentication is needed.


    Default Editor

    This section is only useful if you plan to use the svn program. If you always plan to use a GUI front-end, you can skip this section.

    When committing, svn wants some text for commenting the commit. You can either specify it directly with the -m parameter or by a file with -F or --file. If you do neither of both, svn will run an editor to ask for a comment.

    • TODO: improve this section
    • TODO: better ask the user to modify the svn configuration files?

    This editor is taken either from the svn configuration files or if not defined there from the environment variables: first $SVN_EDITOR, then $VISUAL, then $EDITOR depending which one is defined.

    So maybe you should check your environment variables:

    echo $SVN_EDITOR
    echo $VISUAL
    echo $EDITOR
    

    Check that their settings suit you for your work with svn. If they do not suit you, check your file ~/.bashrc and add something like:

    export SVN_EDITOR=mcedit
    

    Here it sets mcedit, replace it with your favorite editor. Of course you can set $EDITOR instead if you want to change the default editor for you.

    Be careful that if you do not set a command line editor but one that needs X-Window, you will need to run svn always in a X-Window terminal. It might suit you, it might not. Your choice!

    Subversion Configuration

    For proper of svn status and svn diff on KDE sources, you might want to follow the instructions from the developer FAQ for setting up ~/.subversion/config.

    Committing

    Now a few words about how to commit.

    First be sure that the code that you want to commit is right. If you are not certain about a patch, or have some doubts, consider perhaps sending your patch to the relevant mailing list or to the relevant developer if you know who he is.

    Also when committing, please give a useful message with the commit. Think about what you would like to find in, say, two years. (One day, you will probably find out that meaningless commit entries like "Fix" or "Here too" are going to drive you crazy when you have to debug a problem.)

    Good code is not always only about questions like: "Does the code compile?" The code must also fit in what is planned. For example if a new code fixes just one little bug but the maintainer of the code is currently doing a re-write, he will perhaps not be pleased that something has been committed, because he will have to fix all conflicts between the newly committed code and his new code.

    So the best is to communicate (if possible early) to avoid any surprise. A surprised developer is highly at risk of giving a rude answer or at least not a pleasant answer. This is avoidable by communication. Of course, a developer might ask to leave the code alone. Please respect that! (Of course, it does not mean that you should not argue.)

    Commit-Digest

    The KDE Commit-Digest is a weekly overview of the commits to KDE's subversion server. Now that you have a SVN account, you will probably see your own name in there soon!

    The digest features a small statistics section. To improve the accuracy of those, you should add some information, like age or country, about yourself, which you can do here.

    Commit-Filter

    Commit-Filter is a service which allows you to monitor folders (or authors) in SVN for changes, and have each commit's diff emailed to you. This is very useful if you are interested in getting involved in a certain sub-project of KDE and want to keep up with its development.

    Please use reply-to-all when responding to those emails.

    Links

    Subversion
    Using Subversion with KDE
    i18n
    What is i18n and how to use it
    I18N/L10N
    KDE Programmer's i18n howto