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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>GitHub guide — Cyrus IMAP 3.12.1 documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" />
<link rel="stylesheet" href="../../_static/cyrus.css" type="text/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/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/sphinx_highlight.js"></script>
<script src="../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Developer Test Environment" href="developer-testing.html" />
<link rel="prev" title="Overview of Cyrus development environment" href="overview.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../index.html" class="icon icon-home">
Cyrus IMAP
</a>
<div class="version">
3.12.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Cyrus IMAP</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../quickstart.html">Quickstart Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../setup.html">Setup</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../operations.html">Operations</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developers.html">Developers</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../contribute.html">We need your help</a></li>
<li class="toctree-l2"><a class="reference internal" href="documentation.html">Contribute docs</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../developer.html">Contribute code and tests</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../developer.html#getting-started">Getting Started</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="process.html">Development Process</a></li>
<li class="toctree-l4"><a class="reference internal" href="overview.html">Overview of Cyrus development environment</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">GitHub guide</a></li>
<li class="toctree-l4"><a class="reference internal" href="compiling.html">Compiling</a></li>
<li class="toctree-l4"><a class="reference internal" href="../installing.html">Installing Cyrus</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer-testing.html">Developer Test Environment</a></li>
<li class="toctree-l4"><a class="reference internal" href="coverage.html">Test Coverage</a></li>
<li class="toctree-l4"><a class="reference internal" href="jmap.html">JMAP support</a></li>
<li class="toctree-l4"><a class="reference internal" href="install-xapian.html">Xapian for searching</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../developer.html#system-files-and-databases">System files and Databases</a></li>
<li class="toctree-l3"><a class="reference internal" href="../developer.html#resources">Resources</a></li>
<li class="toctree-l3"><a class="reference internal" href="../developer.html#releasing">Releasing</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="cyrusworks.html">Cyrus.Works</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developers.html#cyrus-internals">Cyrus Internals</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developers.html#unit-tests">Unit Tests</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../support.html">Support/Community</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Cyrus SASL</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org/sasl">Cyrus SASL</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">Cyrus IMAP</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../developers.html">Developers</a></li>
<li class="breadcrumb-item"><a href="../developer.html">IMAP Developer Guide</a></li>
<li class="breadcrumb-item active">GitHub guide</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/developer/github-guide.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="github-guide">
<span id="id1"></span><h1>GitHub guide<a class="headerlink" href="#github-guide" title="Permalink to this heading"></a></h1>
<p>A walkthrough for using <a class="reference external" href="https://github.com">GitHub</a> with a view to providing updates (source or documentation or testing) to the <a class="reference external" href="https://github.com/cyrusimap/">Cyrus repository</a>.</p>
<ol class="arabic simple">
<li><p><a class="reference internal" href="#github-guide-account"><span class="std std-ref">Create a GitHub account</span></a></p></li>
<li><p><a class="reference internal" href="#github-guide-sshkey"><span class="std std-ref">Add your ssh key</span></a></p></li>
<li><p><a class="reference internal" href="#github-guide-fork"><span class="std std-ref">Fork the repository</span></a> to make a copy of the code for you to apply changes to.</p></li>
<li><p><a class="reference internal" href="#github-guide-pull"><span class="std std-ref">Issue a pull request</span></a> to request that your changes are incorporated back into the master codebase.</p></li>
</ol>
<p>This guide assumes you are familiar with the workings of <a class="reference external" href="https://help.github.com/articles/set-up-git/">Git</a> for source control.</p>
<section id="create-a-github-account">
<span id="github-guide-account"></span><h2>1. Create a GitHub account<a class="headerlink" href="#create-a-github-account" title="Permalink to this heading"></a></h2>
<p>Go to <a class="reference external" href="https://github.com">GitHub</a> and sign up for an account. You only need the free plan to contribute to Cyrus.</p>
<p>Their <a class="reference external" href="https://help.github.com/articles/signing-up-for-a-new-github-account/">help pages</a> have more information
on filling out your profile and setting up two-factor authentication for additional security.</p>
</section>
<section id="add-your-ssh-key">
<span id="github-guide-sshkey"></span><h2>2. Add your ssh key<a class="headerlink" href="#add-your-ssh-key" title="Permalink to this heading"></a></h2>
<p>It's worth adding a ssh key to your account, so you're not having to input your password every time you access the repository.</p>
<p>If you don't have an ssh key already (and <a class="reference external" href="https://help.github.com/articles/checking-for-existing-ssh-keys/">here's how to check</a>),
you can <a class="reference external" href="https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/">generate a new key</a>. Once you have a key,
<a class="reference external" href="https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/">add it to GitHub</a> and
<a class="reference external" href="https://help.github.com/articles/testing-your-ssh-connection/">test it out</a>.</p>
</section>
<section id="fork-the-repository">
<span id="github-guide-fork"></span><h2>3. Fork the repository<a class="headerlink" href="#fork-the-repository" title="Permalink to this heading"></a></h2>
<p>Whether you're contributing to <a class="reference external" href="https://github.com/cyrusimap/cyrus-imapd">Cyrus</a> (source, or documentation),
or into helping out with <a class="reference external" href="https://github.com/cyrusimap/cyrus-sasl">SASL</a> or
any of the other <a class="reference external" href="https://github.com/cyrusimap">Cyrus component projects</a>, use the Fork button to make a copy of the repository into your own GitHub work space.</p>
<p>GitHub has more information on <a class="reference external" href="https://help.github.com/articles/fork-a-repo/">how to fork a repository</a>.</p>
<p>Once you have a forked copy, you can clone it into your working area on your computer.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">YOUR</span><span class="o">-</span><span class="n">USERNAME</span><span class="o">/</span><span class="n">REPOSITORY</span><span class="o">-</span><span class="n">NAME</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>You will then want to set your local copy to get its changes from the original repository, so it stays in sync. Use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">-v</span></code> to show the current origins of your clone which will currently be your fork.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git remote -v
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
</pre></div>
</div>
<p>We want to set that instead to point to the primary original upstream repository.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">cyrusimap</span><span class="o">/</span><span class="n">REPOSITORY</span><span class="o">-</span><span class="n">NAME</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>Now we can check to see that the upstream is set:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git remote -v
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream https://github.com/cyrusimap/ORIGINAL_REPOSITORY.git (fetch)
upstream https://github.com/cyrusimap/ORIGINAL_REPOSITORY.git (push)
</pre></div>
</div>
<p>We recommend you create a topic branch and make your changes (don't forget to <a class="reference internal" href="developer-testing.html#developer-testing"><span class="std std-ref">test!</span></a>). Using a topic branch means you can keep your master
source in sync without affecting your changes. It also means that if your patch undergoes further revisions before inclusion, you
can easily do so.</p>
</section>
<section id="issue-a-pull-request">
<span id="github-guide-pull"></span><h2>4. Issue a pull request<a class="headerlink" href="#issue-a-pull-request" title="Permalink to this heading"></a></h2>
<p>When your changes are done, you <a class="reference external" href="https://help.github.com/articles/using-pull-requests/">issue a pull request</a>.
This is done by logging into the GitHub interface, swapping to your branch, then selecting New Pull Request.</p>
<p>When submitting the pull request, note if there's a particular filed bug your patch addresses. The Cyrus Team
will review your pull request and make sure it gets integrated!</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="overview.html" class="btn btn-neutral float-left" title="Overview of Cyrus development environment" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="developer-testing.html" class="btn btn-neutral float-right" title="Developer Test Environment" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 1993–2025, The Cyrus Team.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
