Skip to content

Commit ffc267d

Browse files
committedMay 26, 2011
Coding guideline updates for GIT
1 parent ef981f1 commit ffc267d

File tree

6 files changed

+2580
-494
lines changed

6 files changed

+2580
-494
lines changed
 

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,6 @@ scripts/astyle.exe
3434
*.out
3535
*.tex
3636
*.toc
37+
doc/CODING.html
38+
doc/CODING.tex
39+
doc/INSTALL.tex

‎CODING

Lines changed: 92 additions & 306 deletions
Large diffs are not rendered by default.

‎INSTALL

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
Quantum GIS (QGIS)
22
Building QGIS from source - step by step
3+
Thursday May 26, 2011
34

45

5-
Last update: 20110504
6-
Last change: 20110502
6+
Last Updated: Thursday May 26, 2011
7+
Last Change : Tuesday May 24, 2011
78

89

910
1. Introduction
@@ -629,8 +630,8 @@ installed in the default locations):
629630
call "%OSGEO4W_ROOT%\bin\o4w_env.bat"
630631

631632
@set GRASS_PREFIX=c:/OSGeo4W/apps/grass/grass-6.4.0
632-
@set INCLUDE=%INCLUDE%;%OSGEO4W_ROOT%\apps\gdal-17\include;%OSGEO4W_ROOT%\include
633-
@set LIB=%LIB%;%OSGEO4W_ROOT%\apps\gdal-17\lib;%OSGEO4W_ROOT%\lib
633+
@set INCLUDE=%INCLUDE%;%OSGEO4W_ROOT%\include
634+
@set LIB=%LIB%;%OSGEO4W_ROOT%\lib;%OSGEO4W_ROOT%\lib
634635

635636
@cmd
636637

@@ -1666,3 +1667,6 @@ The following people have contributed to this document:
16661667
- Tim Sutton 2006
16671668
- Debian package section: Juergen Fischer 2008
16681669

1670+
- Latex Generator
1671+
- Tim Sutton 2011
1672+

‎doc/CODING.t2t

Lines changed: 87 additions & 183 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ Developers guide for QGIS
7777
% format, then paste the procedure in below. I have instated these changes so
7878
% that we can have a single central document that contains all the instructions
7979
% developers contributing to QGIS. This page should always reflect the most
80-
% current SVN trunk build procedure - for release versions the CODING document
80+
% current GIT master build procedure - for release versions the CODING document
8181
% in the sources will be generated according to the current build procedure at
8282
% the time.
8383

@@ -184,22 +184,11 @@ example:
184184
***************************************************************************/
185185
```
186186

187-
=== SVN Keyword ===
188-
Each source file should contain the $Id$ keyword. This will be expanded by SVN
189-
to contain useful information about the file, revision, last committer, and
190-
date/time of last checkin.
187+
=== Keyword Substitution ===
191188

192-
Place the keyword right after the standard header/license that is found at the
193-
top of each source file:
194-
```
195-
/* $Id$ */
196-
```
197-
198-
You also need to set
199-
200-
svn propset svn:keywords "Id"
201-
202-
for the new files.
189+
In the days of SVN we used to require that each source file should contain the
190+
$Id$ keyword. Keyword substitution is not supported by GIT and so should no
191+
longer be used.
203192

204193
== Variable Names ==
205194
Variable names begin with a lower case letter and are formed using mixed case.
@@ -416,45 +405,48 @@ You should also really read this article from Qt Quarterly on
416405

417406

418407

419-
= SVN Access =
408+
= GIT Access =
420409

421-
This page describes how to get started using the QGIS Subversion repository
410+
This section describes how to get started using the QGIS GIT repository. Before you can do this, you need to first have a git client installed on your system. Debian based distro users can do:
422411

423-
== Accessing the Repository ==
424-
To check out QGIS HEAD:
425412
```
426-
svn --username [your user name] co https://svn.osgeo.org/qgis/trunk/qgis
413+
sudo apt-get install git
427414
```
428415

416+
Windows users can obtain [msys git http://code.google.com/p/msysgit/].
417+
429418

430-
== Anonymous Access ==
431-
You can use the following commands to perform an anonymous checkout from the
432-
QGIS Subversion repository. Note we recommend checking out the trunk (unless
433-
you are a developer or really HAVE to have the latest changes and don't mind
434-
lots of crashing!).
435419

436-
You must have a subversion client installed prior to checking out the code. See
437-
the Subversion website for more information. The Links page contains a good
438-
selection of SVN clients for various platforms.
420+
== Accessing the Repository ==
421+
422+
To clone QGIS master:
439423

440-
To check out a branch
441424
```
442-
svn co https://svn.osgeo.org/qgis/branches/<branch name>
425+
git://github.com/qgis/Quantum-GIS.git
443426
```
444427

445-
To check out SVN stable trunk:
428+
== Check out a branch ==
446429

430+
To check out a branch, for example the release 1.7.0 branch do:
447431
```
448-
svn co https://svn.osgeo.org/qgis/trunk/qgis qgis_trunk
432+
cd Quantum-GIS
433+
git fetch
434+
git branch --track origin release-1_7_0
435+
git checkout release-1_7_0
436+
449437
```
450438

451-
/!\ **Note:** If you are behind a proxy server, edit your ~/subversion/servers
452-
file to specify your proxy settings first!
439+
To check out the master branch:
453440

454-
/!\ **Note:** In QGIS we keep our most stable code in the version 1_0 branch.
455-
Trunk contains code for the so called 'unstable' release series. Periodically
456-
we will tag a release off trunk, and then continue stabilisation and selective
457-
incorporation of new features into trunk.
441+
```
442+
cd Quantum-GIS
443+
git checkout master
444+
```
445+
446+
/!\ **Note:** In QGIS we keep our most stable code in the current release branch.
447+
Master contains code for the so called 'unstable' release series. Periodically
448+
we will branch a release off master, and then continue stabilisation and selective
449+
incorporation of new features into master.
458450

459451
See the INSTALL file in the source tree for specific instructions on building
460452
development versions.
@@ -466,19 +458,17 @@ If you're interested in checking out Quantum GIS documentation sources:
466458
svn co https://svn.osgeo.org/qgis/docs/trunk qgis_docs
467459
```
468460

461+
/!\ **Note:** This url will change to a git URL in the near future.
462+
469463
You can also take a look at DocumentationWritersCorner for more information.
470464

471-
== SVN Documentation ==
472-
473-
The repository is organized as follows:
474-
475-
http://wiki.qgis.org/images/repo.png
476-
477-
See the Subversion book http://svnbook.red-bean.com for information on becoming
478-
a SVN master.
479-
465+
== GIT Documentation ==
480466

467+
See the following sites for information on becoming a GIT master.
481468

469+
http://gitref.org
470+
http://progit.org
471+
http://gitready.com
482472

483473
== Development in branches ==
484474

@@ -488,8 +478,8 @@ last years. Therefore it is hard to anticipate the side effects that the
488478
addition of a feature will have. In the past, the QGIS project had very long
489479
release cycles because it was a lot of work to reetablish the stability of the
490480
software system after new features were added. To overcome these problems, QGIS
491-
switched to a development model where new features are coded in svn branches
492-
first and merged to trunk (the main branch) when they are finished and stable.
481+
switched to a development model where new features are coded in GIT branches
482+
first and merged to master (the main branch) when they are finished and stable.
493483
This section describes the procedure for branching and merging in the QGIS
494484
project.
495485

@@ -503,75 +493,43 @@ technical advisor of the project steering committee (PSC). If the new feature
503493
requires any changes to the QGIS architecture, a request for comment (RFC) is
504494
needed.
505495

506-
- **Create a branch:**
507-
Create a new svn branch for the development of the new feature (see
508-
UsingSubversion for the svn syntax). Now you can start developing.
509-
510-
- **Merge from trunk regularly:**
511-
It is recommended to merge the changes in trunk to the branch on a regular
512-
basis. This makes it easier to merge the branch back to trunk later.
513-
514-
- **Documentation on wiki:**
515-
It is also recommended to document the intended changes and the current status
516-
of the work on a wiki page.
517-
518-
- **Testing before merging back to trunk:**
519-
When you are finished with the new feature and happy with the stability, make
520-
an announcement on the developer list. Before merging back, the changes will
521-
be tested by developers and users. Binary packages (especially for OsX and
522-
Windows) will be generated to also involve non-developers. In trac, a new
523-
Component will be opened to file tickets against. Once there are no remaining
524-
issues left, the technical advisor of the PSC merges the changes into trunk.
525-
526-
-
527-
528-
=== Creating a branch ===
529-
530-
We prefer that new feature developments happen out of trunk so that trunk
531-
remains in a stable state. To create a branch use the following command:
496+
**Create a branch:**
497+
Create a new GIT branch for the development of the new feature.
532498

533499
```
534-
svn copy https://svn.osgeo.org/qgis/trunk/qgis https://svn.osgeo.org/qgis/branches/qgis_newfeature
535-
svn commit -m "New feature branch"
500+
git branch newfeature
501+
git checkout newfeature
536502
```
537503

538-
=== Merge regularly from trunk to branch ===
539-
540-
When working in a branch you should regularly merge trunk into it so that your
541-
branch does not diverge more than necessary. In the top level dir of your
542-
branch, first type ```svn info``` to determine the revision numbers of your
543-
branch which will produce output something like this:
504+
Now you can start developing. If you plan to do extensive on that branch, would
505+
like to share the work with other developers, and have write access to the
506+
upstream repo, you can push your repo up to the QGIS official repo by doing:
544507

545508
```
546-
timlinux@timlinux-desktop:~/dev/cpp/qgis_raster_transparency_branch$ svn info
547-
Caminho: .
548-
URL: https://svn.osgeo.org/qgis/branches/raster_transparency_branch
549-
Raiz do Repositório: https://svn.osgeo.org/qgis
550-
UUID do repositório: c8812cc2-4d05-0410-92ff-de0c093fc19c
551-
Revisão: 6546
552-
Tipo de Nó: diretório
553-
Agendado: normal
554-
Autor da Última Mudança: timlinux
555-
Revisão da Última Mudança: 6495
556-
Data da Última Mudança: 2007-02-02 09:29:47 -0200 (Sex, 02 Fev 2007)
557-
Propriedades da Última Mudança: 2007-01-09 11:32:55 -0200 (Ter, 09 Jan 2007)
509+
git push origin newfeature
558510
```
559511

560-
The second revision number shows the revision number of the start revision of
561-
your branch and the first the current revision. You can do a dry run of the
562-
merge like this:
512+
**Note:** if the branch already exists your changes will be pushed into it.
513+
514+
**Merge from master regularly:**
515+
It is recommended to merge the changes in master to the branch on a regular
516+
basis. This makes it easier to merge the branch back to master later.
563517

564518
```
565-
svn merge --dry-run -r 6495:6546 https://svn.osgeo.org/qgis/trunk/qgis
519+
git merge master
566520
```
567521

568-
After you are happy with the changes that will be made do the merge for real
569-
like this:
522+
**Documentation on wiki:**
523+
It is also recommended to document the intended changes and the current status
524+
of the work on a wiki page.
570525

571-
```
572-
svn merge -r 6495:6546 https://svn.osgeo.org/qgis/trunk/qgis
573-
svn commit -m "Merged upstream changes from trunk to my branch"
574-
```
526+
**Testing before merging back to master:**
527+
When you are finished with the new feature and happy with the stability, make
528+
an announcement on the developer list. Before merging back, the changes will
529+
be tested by developers and users. Binary packages (especially for OsX and
530+
Windows) will be generated to also involve non-developers. In trac, a new
531+
Component will be opened to file tickets against. Once there are no remaining
532+
issues left, the technical advisor of the PSC merges the changes into master.
575533

576534

577535
== Submitting Patches ==
@@ -582,7 +540,7 @@ easily, and help us deal with the patches that are sent to use easily.
582540
=== Patch file naming ===
583541

584542
If the patch is a fix for a specific bug, please name the file with the bug
585-
number in it e.g. **bug777fix.diff**, and attach it to the original bug report
543+
number in it e.g. **bug777fix.patch**, and attach it to the original bug report
586544
in trac (https://trac.osgeo.org/qgis/).
587545

588546
If the bug is an enhancement or new feature, its usually a good idea to create
@@ -592,27 +550,22 @@ a ticket in trac (https://trac.osgeo.org/qgis/) first and then attach you
592550

593551
This makes it easier for us to apply the patches since we don't need to
594552
navigate to a specific place in the source tree to apply the patch. Also when I
595-
receive patches I usually evaluate them using kompare, and having the patch
553+
receive patches I usually evaluate them using merge, and having the patch
596554
from the top level dir makes this much easier. Below is an example of how you
597555
can include multiple changed files into your patch from the top level
598556
directory:
599557

600558
```
601-
cd qgis
602-
svn diff src/ui/somefile.ui src/app/somefile2.cpp > bug872fix.diff
559+
cd Quantum-GIS
560+
git checkout master
561+
git pull origin master
562+
git checkout newfeature
563+
git format-patch master --stdout > bug777fix.patch
603564
```
604565

605-
=== Including non version controlled files in your patch ===
606-
607-
If your improvements include new files that don't yet exist in the repository,
608-
you should indicate to svn that they need to be added before generating your
609-
patch e.g.
610-
611-
```
612-
cd qgis
613-
svn add src/lib/somenewfile.cpp
614-
svn diff > bug7887fix.diff
615-
```
566+
This will make sure your master branch is in sync with the upstream repository,
567+
and then generate a patch which contains the delta between your feature branch
568+
and what is in the master branch.
616569

617570
=== Getting your patch noticed ===
618571

@@ -632,7 +585,7 @@ under the GPL.
632585

633586

634587

635-
== Obtaining SVN Write Access ==
588+
== Obtaining GIT Write Access ==
636589

637590
Write access to QGIS source tree is by invitation. Typically when a person
638591
submits several (there is no fixed number here) substantial patches that
@@ -646,74 +599,25 @@ demonstrated ability to submit patches and should ideally have submitted several
646599
substantial patches that demonstrate their understanding of modifying the code
647600
base without breaking things, etc.
648601

602+
**Note:** Since moving to GIT, we are less likely to grant write access to new
603+
developers since it is trivial to share code within github by forking QGIS and
604+
then issuing pull requests.
649605

650606

651-
=== Procedure once you have access ===
652-
653-
654-
Checkout the sources:
655-
656-
```
657-
svn co https://svn.osgeo.org/qgis/trunk/qgis qgis
658-
```
659-
660-
661-
Build the sources (see INSTALL document for proper detailed instructions)
662-
663-
```
664-
cd qgis
665-
mkdir build
666-
ccmake .. (set your preferred options)
667-
make
668-
make install (maybe you need to do with sudo / root perms)
669-
```
670-
671-
Make your edits
672-
673-
```
674-
cd ..
675-
```
676-
677-
Make your changes in sources. Always check that everything compiles before
678-
making any commits. Try to be aware of possible breakages your commits may
679-
cause for people building on other platforms and with older / newer versions of
607+
Always check that everything compiles before making any commits / pull
608+
requests. Try to be aware of possible breakages your commits may cause for
609+
people building on other platforms and with older / newer versions of
680610
libraries.
681611

682-
683-
Add files (if you added any new files). The svn status command can be used to
684-
quickly see if you have added new files.
685-
686-
```
687-
svn status src/pluguns/grass/modules
688-
```
689-
690-
Files listed with ? in front are not in SVN and possibly need to be added by
691-
you:
692-
693-
```
694-
svn add src/pluguns/grass/modules/foo.xml
695-
```
696-
697-
Commit your changes
698-
699-
```
700-
svn commit src/pluguns/grass/modules/foo.xml
701-
```
702-
703-
Your editor (as defined in $EDITOR environment variable) will appear and you
704-
should make a comment at the top of the file (above the area that says 'don't
705-
change this'. Put a descriptive comment and rather do several small commits if
706-
the changes across a number of files are unrelated. Conversely we prefer you to
707-
group related changes into a single commit.
708-
709-
Save and close in your editor. The first time you do this, you should be
710-
prompted to put in your username and password. Just use the same ones as your
711-
trac account.
712-
612+
When making a commit, your editor (as defined in $EDITOR environment variable)
613+
will appear and you should make a comment at the top of the file (above the
614+
area that says 'don't change this'. Put a descriptive comment and rather do
615+
several small commits if the changes across a number of files are unrelated.
616+
Conversely we prefer you to group related changes into a single commit.
713617

714618
= Unit Testing =
715619

716-
As of November 2007 we require all new features going into trunk to be
620+
As of November 2007 we require all new features going into master to be
717621
accompanied with a unit test. Initially we have limited this requirement to
718622
**qgis_core**, and we will extend this requirement to other parts of the code base
719623
once people are familiar with the procedures for unit testing explained in the

‎doc/INSTALL.html

Lines changed: 2383 additions & 0 deletions
Large diffs are not rendered by default.

‎doc/build.sh

100644100755
Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
#!/bin/bash
22
txt2tags -o ../INSTALL -t txt INSTALL.t2t
3-
txt2tags -o index.html -t html INSTALL.t2t
3+
txt2tags -o INSTALL.html -t html INSTALL.t2t
4+
txt2tags -o INSTALL.tex -t tex INSTALL.t2t
5+
pdflatex INSTALL.tex
6+
mv INSTALL.pdf ..
47
txt2tags -o ../CODING -t txt CODING.t2t
58
txt2tags -o CODING.html -t html CODING.t2t
9+
txt2tags -o CODING.tex -t tex CODING.t2t
10+
pdflatex CODING.tex
11+
mv CODING.pdf ..

0 commit comments

Comments
 (0)
Please sign in to comment.