-
Notifications
You must be signed in to change notification settings - Fork 1
/
guide.en.html
170 lines (162 loc) · 9.03 KB
/
guide.en.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Open Source Contributions — AMC Traffic Server Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Completed Projects" href="completed.en.html" />
<link rel="prev" title="Diagrams" href="reference.en.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="completed.en.html" title="Completed Projects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="reference.en.html" title="Diagrams"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">SWOC Docs</a> »</li>
<li class="nav-item nav-item-this"><a href="">Open Source Contributions</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="open-source-contributions">
<span id="guides"></span><h1>Open Source Contributions<a class="headerlink" href="#open-source-contributions" title="Permalink to this headline">¶</a></h1>
<p>Contributing to open source can be a struggle given the variety of concerns from the community.
Overall, however, my view is that code is made stronger by surviving the gauntlet. There are many
skilled developers in the community who will often see things you miss.</p>
<p>The community has undergone rather a lot of growth lately and so is still adapting to an overall
group where it it not the case that every one knows every one else from chat and summits and there
is a shared understanding of what makes a good pull request. The following are I think the most basic
and important things to keep in mind that will help ease the process.</p>
<dl class="simple">
<dt>Separability</dt><dd><p>Pull requests should be as small as possible. This yields the important result that isolating
changes that cause problems and recovering from them is much easier. This means that if new
classes / technology / support is required for a pull request, it is almost always better to
contribute it in a separate, prior pull request. Pull requests that have a lot of new classes and
other things have a very difficult time, both because the additional support obscures the real
point of the pull request and that discussions can get bogged down on details in the support that
aren’t critical for the overall work.</p>
</dd>
<dt>Parsimony</dt><dd><p>There is a general concern about code bloat and much effort has been made in the past to decrease
the over all code size. For what Traffic Server can do it has a remarkably small code base. This is not an
accident. For this reason think twice, then reconsider again, if you really need to add a support
class. Avoid this if you can, especially if the class is used only once or in limited
circumstances. Also avoid putting classes in separate files if the class isn’t used in other file
scopes. See if there are existing classes or other techniques which, with a bit of work, could be
made to suffice.</p>
</dd>
<dt>Consistency</dt><dd><p>Traffic Server is an old project with people who have been working on it for over a decade. They are
comfortable with where things are and how things are done. This doesn’t mean it’s perfect but
unless there is a strong reason to change, you should peruse the code and try to do things in a
similar way. One example would be initialization. There are various ways to do this in C++, most
of which result in the same machine code. Therefore it’s a reasonable expectation that you will
do this in the same way as the existing code. As a newcomer to the community, try to show a bit
of respect for existing customs and habits, <em>especially</em> when such things have no real impact on
code quality.</p>
</dd>
</dl>
<section id="c-guidelines">
<h2>C++ Guidelines<a class="headerlink" href="#c-guidelines" title="Permalink to this headline">¶</a></h2>
<p>Some basics are here in the <a class="reference external" href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=65146830">C++11 Usage Guide</a>.</p>
<section id="memory-and-allocation">
<h3>Memory and Allocation<a class="headerlink" href="#memory-and-allocation" title="Permalink to this headline">¶</a></h3>
<p>The main path of Traffic Server execution is very sensitve to blocking or delay. For this reason memory
allocation should be strongly minimized. It is frequently the case the reasonable maximums can be
determined and needed memory allocated on the stack or statically. This is particularly true for
temporaries. One example is file path names. There is a operating system based maximum length,
<code class="code docutils literal notranslate"><span class="pre">PATH_NAME_MAX</span></code>, which is the longest path Traffic Server will handle. A path used only in a local scope
can be put in stack allocated buffer of that length without any memory allocation at all.</p>
<p>Use of STL containers should be avoided where possible, except for <code class="code docutils literal notranslate"><span class="pre">std::vector</span></code>.</p>
</section>
</section>
<section id="additional-reference-pages">
<h2>Additional reference pages<a class="headerlink" href="#additional-reference-pages" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=65146830">Basic coding style</a>.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/balcora-gate-400x400.jpg" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Open Source Contributions</a><ul>
<li><a class="reference internal" href="#c-guidelines">C++ Guidelines</a><ul>
<li><a class="reference internal" href="#memory-and-allocation">Memory and Allocation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#additional-reference-pages">Additional reference pages</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="reference.en.html"
title="previous chapter">Diagrams</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="completed.en.html"
title="next chapter">Completed Projects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/guide.en.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="completed.en.html" title="Completed Projects"
>next</a> |</li>
<li class="right" >
<a href="reference.en.html" title="Diagrams"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">SWOC Docs</a> »</li>
<li class="nav-item nav-item-this"><a href="">Open Source Contributions</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2017, amc@apache.org.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.1.2.
</div>
</body>
</html>