Follow-up to EM-Merge: fixed a php warning
[Packages/TYPO3.CMS.git] / misc / core_svn_rules.txt
1 *******************************************************
2 Rules and Conditions for contributions to Core SVN
3 (Core + System Extensions)
4 *******************************************************
6 [A] Development Principle: A bazaar of small cathedrals.
7 - Each part of the system (System extensions, scripts, functions) has a person responsible and in charge of the development of that part.
8 - All or nothing; If a part of the system is not maintained according to the "General Rules of Core Development" (see below) and we need to release the core, we will revert to previous stable version of that part of the system.
9 - The Core Team Leader (Kasper) is ultimately in charge.
10 Note: This makes it possible for many to work together while maintaining control and tracking responsibility more easily. Also it offers boths modes of development: Group and solo.
13 [B] Committing changes to Core SVN
14 - As long as changes follow the "General Rules of core development" (see below), the mode of commits is determined by the person responsible for that particular part.
15 - Examples:
16 - A developer of a certain class might want to maintain it all alone and not accept any commits by others.
17 - A developer of an extension might want to collaborate in a larger group quite anarchical.
20 [C] General Rules of Core Development:
21 - 1: CGL Adherance.
22 Code in the core must follow the Coding Guidelines for TYPO3 to appear as a unity and good examples. This includes (but is not limited to) code formatting, XHTML compliance and full inline code documentation.
23 - 2: Pursue Stability.
24 "Rather a stable bug than an unstable system". TYPO3 is known for being stable (even in beta versions and SVN) and we want it to stay that way. Give priority to stability, organize quality assurance, create unit-tests for mission critical parts of your code.
25 - 3: Backwards Compatibility
26 We aim at being very backwards compatible so even old websites can easily upgrade to most recent TYPO3 core source. Contrary to general extensions where people can easily choose to keep running an old version, all system extensions in the core (and the core code itself) has to respect that they are not (easily) downgradable. Hence they must respect backwards compatibility for the larger parts.
27 - 4: No loose ends
28 Do NOT implement things half-way. Begin, go through it, round it up, complete it - because you will never get back to it again!
29 - 5: Document instantly!
30 There are two extremes of documentation: References (list of options, eg. TSref) and tutorials (walk-throughs). Tutorials are nice but not mission critical as references are! *Always* maintain reference documentation along the work! You have forgotten tomorrow!
31 - 6: Branches?
32 Do not create branches/tags without getting permission from Kasper. By default he is the only one doing it unless expressly allowed.
33 - 7: Adding / Removing files?
34 You may NOT add or remove scripts to the core without asking Kasper first (unless inside a directory totally controlled by you, like for instance a system extension of course).
37 [D] Rules of SVN Commits to Kaspers Core parts:
38 Now, here comes the rules for commits to my parts of the core (which is everything you are not sure belongs to someone else.)
39 These rules take offset in the presupposition that I'm the bottleneck and we all want to cut down my administration time as much as possible. Effectively it may mean that the "command-chain" for you as a contributer is getting longer and more cumbersome. If you disagree with this presupposition, just tell me why.
41 Secret #1: I *will* check everything!
42 - I require to be 100% in control of all commits to my parts of the core. This means you can easily step very hard on my toes if you break the rules below. So read them and commit with care!
44 Rule #1: Ask me first!
45 - 1) Always contact me by email first and present a summary of what you want to do. If it sounds reasonable I will probably say "Send me a unified diff-patch" and if that seems ok I will say "Yes, just commit". The point is that I get a chance to reject things which will just be a mess to clean up.
46 - 2) Exception: If you are justified in thinking it wouldn't be necessary (for instance doing a second commit to something we have already discussed).
47 - 3) If you ask first, we can prevent these past (bad) experiences:
48 - a) My code overview is typically larger and I may see implications that were not clear to you. This prevents bugs and bad implementations.
49 - b) Maybe another similar concept is planned. In that case we should wait for that.
50 - 4) Balance is important. Juggling with a big project like TYPO3 is an act of balance and some changes/fixes will (potentially) disturb the balance. If I judge that to be the case, I will reject the suggestion with reference to my 6th sense... :-)
51 - 5) I'm itchy; With SVN I have already experienced that commits meant that I was forced into bugfixing others code for a long time... This is very bad experience! I will do anything to avoid that.
53 Rule #2: Reference Documentation instantly!
54 - This is General Rules #5 emphasized! I'm very, very serious about this point. I really hate to preview some code and see that a new feature was added but not called to my notice! I'm not talking about writing 5 pages, I'm talking about making a small bulletlist with [option] - [description] and sending it to me so we don't forget it!
55 - Specific Examples:
56 - You add "inverseMenuItemOrder" property somewhere in TypoScript. Instantly you note down 5 things: a) property name, b) TS data type, c) Description, d) optional default value and e) Which table in TSref (or elsewhere) to put it!
57 - You add new key in some global PHP array. Instantly you note down 3 things: a) variable name + new key, b) Description of what it does in an understanable way, c) pointer to where in the TYPO3 documents it should go. If you don't know where it belongs then still send it and just say so!!!
58 - You add a new hook in the system. Since there is currently no place where hooks are documented you cannot really do anything. If it deserves a comment then send one for any future documentation. In any case, send me a notice about the situation.
60 Rule #3: No loose ends
61 - This is General Rules #4 emphasized! Before you begin core work, make sure you have allocated the time to finish it to an acceptable standard (by the measures given in this text)
62 - It needs to be said although it should be obvious: Any code committed to SVN must be tested properly. Parsing errors in particular are not acceptable!
65 - General request for my opinion
66 - If OK, sending an actual Patch-diff to me for approval
67 - If approval,
68 - send any necessary documentation to me
69 - commit code to SVN
72 [E] Rules of SVN Commits for parts of the core NOT maintained by Kasper
73 ... (yet to be filled in from other contributers, like Rene Fritz who is in charge of eg. Services)
76 [F] Version number scheme
77 Versioning scheme:
78 - major.minor.patch[alpha/beta/RC][-dev]
79 - major and minor: Incremented based on the extend of new features (in HEAD branch)
80 - patch: incremented only for important bugfixes in a release branch.
81 - dev is always used for intermediate SVN stuff.
82 - [alpha/beta/RC] is used only for major releases where this procedure is necessary. These releases have always a trailing number, counting from 1 to n.
83 - HEAD branch is the continuous development of TYPO3. We use only this branch for new development of the Core.
84 - Each time we have a Release Candidate which is so stable we believe it to be the final release we will make a "release branch" tagged "TYPO3_[major]-[minor]". The Quality Ensurance team / Package team represented by Ingmar Schlecht and Michael Stucki are in charge of managing the release branches, make new patch releases, tag and merge bugfixes in the release branches.
85 - In the release branches tagging is used for each release on the form "TYPO3_[major]-[minor]-[patch]"
87 Examples of BRANCHES (major/minor releases):
88 - Major releases where we feature-freeze before release and backport fixes to.
89 TYPO3_3-6
90 TYPO3_3-7
91 TYPO3_4-0
93 Examples of TAGS (patch releases):
94 - Indicates release points in time.
95 TYPO3_3-7-0RC2 (RC2 for main release)
96 TYPO3_3-7-0 (main release)
97 TYPO3_3-7-1 (patch release)
98 TYPO3_3-7-2 (patch release)
100 Example:
101 For the 3.7.0 launch the RC2 event will be a feature freeze. Therefore the branch "TYPO3_3-7" is created there meaning:
102 - Final fixes (and future hotfixes) is done in that branch
103 - Development for 3.8.0 could go on in HEAD
104 At the same time the tag "TYPO3_3-7-0RC2" was applied basically because the branch-point coincided with the RC2. If an RC3 would come that would be tagged in the "TYPO3_3-7-0RC3" branch. The final release gets the tag "TYPO3_3-7-0" to indicate the point of release.
107 [G] Modifying / maintaining external projects which are merged into TYPO3core
108 The following directories are merged from other sources and MUST NOT be modified unless there is a very good reason to do so:
109 - typo3/sysext/dbal/
110 - typo3/sysext/extbase/
111 - typo3/sysext/fluid/
113 In order to modify these extensions, contact the development team of the relevant extension.
115 How to merge changes from external sources (only for maintainers!)
116 1. Check the last synched version (noted in extname/last_synched_target)
117 2. Merge from this target and the new version:
118 $ svn merge [last_synched_target] [new_target] typo3/sysext/extbase/
119 3. Before committing, update extname/last_synched_target
120 4. Commit the changes. Commit message must be "Merge with [extension] [version]"