Squid Merge Procedure
In order to clean up the quality of code entering Squid, the core developers have arranged these simple requirements and procedure for submissions.
Back to DeveloperResources.
Before spending time coding, its best to discover whether or not the code is needed or useful.
We would like everyone to discuss their plans in the squid-dev mailing list (its open to anyone). So that we can
- assist new developers in finding the best way to add their features
- and, prevent duplication of effort (your feature may be half-developed already)
- and, sometimes the feature wanted already exists in a unexpected way.
Other developers are often able to provide projects for anyone just wanting to contribute.
SquidCodingGuidelines lists the fine details of syntax required.
- Formatting is presently enforced automatically post-commit.
Self-checks may be done using the scripts/source-maintenance.sh script (requires astyle 1.23 for full checks).
Submissions are emailed to squid-dev for merging, one submission per post. The submission email must contain:
Subject: The name of the new feature or a brief change description, prefixed with [PATCH].
Main body: A full description of the new feature or change. The description guides those reading your code. Its verbatim copy is usually used as the commit message if your submission is accepted.
Attachment: A bzr merge bundle or a manual patch in a unified diff format.
Suitability for Merge
Please try to not commit unfinished stuff needing more code to actually work the way intended. trunk is meant for sharing working code updates with earlybird testers. Development is supposed to be done on branches before merging.
If a follow up change (bugfix etc) is committed related to an earlier change please refer to the subject (first line) of the previous change in the commit message.
If you suspect that there will be a series of incremental commits relating to a specific feature or reorganization then make the subject line easy to connect together by starting the title line with a short feature name: (i.e. "rproxy: header fixes")
Add to the below merging procedure any additional testing/documentation steps you think makes sense. Use of common sense is the main rule of conduct.
Audit and Merging Steps
Check that you have added release notes, if any are needed: doc/release-notes/release-X.sgml. Don't worry about the HTML or TXT files, they are automatically built by the maintainer. Only the SGML files need updating.
- If applicable, check that you have added the feature sponsor to the SPONSORS file.
- If applicable, check that you have added the code copyright license to the CREDITS file.
Bring your development branch up to date as described in: BzrInstructions
Run a full build test: ./test-builds.sh. Or use the build farm branch matrix build farm (requires an account).
- Fix ALL issues with your code uncovered by that testing. If you are certain a problem is with the trunk code, discuss it on squid-dev.
When your code passes testing, Submit a merge bundle or patch for auditing. see above.
- Read reviews and address feedback, if any. This step may require re-coding and resubmitting your work or defending your choices until your submission is accepted (i.e., gets a passing vote, see below).
Submissions are normally merged on the next maintenance cycle after acceptance (usually weekends).
The first matching rule wins. A submission is automatically counted as one positive vote from the submitter.
Any developer may vote.
- One negative vote by a core developer blocks the merge until resolved.
- Two positive votes from core developers accept the submission (with a high priority for merging).
- Any three positive votes accept the submission.
- Submissions older than 10 days without negative votes are accepted.
- Core developers may commit any changes immediately.
- Within 10 days of the commit, core developers may remove any submission without prior notice or discussion. A post-factum notice (and discussion) are still expected on squid-dev.
The core developers mentioned above are experienced developers with serious long-term dedication and contribution to the Squid project as a whole and Squid code in particular. They are usually active on squid-dev and often perform the auditing duties personally. Core folks have collective responsibility for the Squid project and may use their super powers to resolve conflicts or prevent disasters.