-
Notifications
You must be signed in to change notification settings - Fork 3
/
best-practices-in-a-collaborative-environment.html
368 lines (293 loc) · 18.3 KB
/
best-practices-in-a-collaborative-environment.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
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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
<!DOCTYPE html>
<html lang="en">
<head>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-112480279-1');
</script>
<meta charset="utf-8">
<title>channelCS - Best practices in a collaborative environment</title>
<meta name="description" content="">
<meta name="author" content="channelCS">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
<!--[if lt IE 9]>
<script src="/theme/html5.js"></script>
<![endif]-->
<!-- Le styles -->
<link href="/theme/bootstrap.min.css" rel="stylesheet">
<link href="/theme/bootstrap.min.responsive.css" rel="stylesheet">
<link href="/theme/local.css" rel="stylesheet">
<link href="/theme/pygments.css" rel="stylesheet">
<!-- So Firefox can bookmark->"abo this site" -->
<link href="/feeds/all.atom.xml" rel="alternate" title="channelCS" type="application/atom+xml">
</head>
<body>
<div class="navbar">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="">channelCS</a>
<div class="nav-collapse">
<ul class="nav">
</ul>
</div>
</div>
</div>
</div>
<div class="container">
<div class="content">
<div class="row">
<div class="span9">
<div class='article'>
<div class="content-title">
<h1>Best practices in a collaborative environment</h1>
Tue 03 April 2018
by <a class="url fn" href="/author/akshita-gupta-aditya-arora.html">Akshita Gupta, Aditya Arora</a>
</div>
<div><p>This blog post is made possible due to amazing mentors <a href="https://github.com/djmitche">Dustin</a>, <a href="https://github.com/eliperelman">Eli</a>, <a href="https://github.com/helfi92">Hassan</a> and, <a href="https://github.com/emmairwin">Emma</a>.</p>
<p>This is a place for all newcomers to Open Source to get an idea for getting started with version control systems and contributing to Open Source projects. It is totally different in maintaining your own projects as compared to working with multiple people in order to create a single great product.</p>
<p>As an Outreachy aspirant, I have been working for the past two months, solving multiple issues in Mozilla's <a href="https://github.com/taskcluster/taskcluster-tools">Taskcluster</a> and <a href="https://github.com/mozilla/diversity">Diversity</a> projects.
They have awesome mentors who have been really helpful in making me understand my mistakes. I want to share these practices with everyone in order to skip those mistakes.</p>
<h2>1. Welcome to Open Source</h2>
<p>If you are a newcomer, I want to welcome you to this <em>one-of-a-kind</em> great place called as OpenSource . It is a place to showcase your work and at the same time help others to make awesome projects. Remember, <strong>Every organisation is different.</strong> They have their own set of standards and rules to follow. In this blog post, however, I would like to give you a general introduction and practices which covers most of the organisations. </p>
<h3>1.1 Getting Started</h3>
<p>Firstly, go through the organisations' Github pages and look through the repositories. Find out those which interests you. Once you have selected a repo</p>
<ul>
<li>Go through the <strong>README</strong> and understand the working of the project.</li>
<li>Follow the instructions in the README and set up the project on your local machine.</li>
<li>Explore the project's codebase. If you find any error or bug, generate an <strong>Issue</strong>.</li>
<li>If you are unable to find anything, somebody else might have. Go to the <strong>Issues</strong> tab of the project to find some issues being worked upon.</li>
</ul>
<p><strong>Don't know coding and still want to contribute?</strong> Don't be disheartened. Let's get our facts correct- <em>A human being cannot learn every programming language.</em> You might be good at writing. There are various projects that need an incredible writer like you. You can always look for the <em>Documentation</em> tag in an Issue or generate a new one in case you find a repo that needs documentation. You can also learn while contributing. I believe, the logic of all the programming languages is similar. The major difference lies in the syntax. If you know how the project works, the syntax should not be an obstacle in your path.</p>
<h3>1.2 Forking the repo</h3>
<p>You cannot make changes directly to the organisation's repo. For that, you need to make a copy into your own profile. Click on the
<!-- Place this tag where you want the button to render. -->
<button><svg viewBox="0 0 10 16" height="16"><path fill-rule="evenodd" d="M8 1a1.993 1.993 0 0 0-1 3.72V6L5 8 3 6V4.72A1.993 1.993 0 0 0 2 1a1.993 1.993 0 0 0-1 3.72V6.5l3 3v1.78A1.993 1.993 0 0 0 5 15a1.993 1.993 0 0 0 1-3.72V9.5l3-3V4.72A1.993 1.993 0 0 0 8 1zM2 4.2C1.34 4.2.8 3.65.8 3c0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2zm3 10c-.66 0-1.2-.55-1.2-1.2 0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2zm3-10c-.66 0-1.2-.55-1.2-1.2 0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2z"></path></svg> Fork</button> button to get your own copy of the repository. </p>
<h3>1.3 Cloning the repo</h3>
<p>You can now clone the repo in a local system to make the changes. Type</p>
<div class="highlight"><pre><span></span>git clone https://github.com/<your-username>/<repo-name>.git
</pre></div>
<p>in bash to get the repository on your computer.</p>
<h2>2. Working on issues</h2>
<p>You might have found a bug or want to work on an Issue that interests you. If you found a bug, go through the <button><svg class="octicon octicon-issue-opened" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg> Issue</button> tab to see if an issue is already generated or not. If not, you may generate a new issue.</p>
<h3>2.1 Asking to get assigned</h3>
<p>Make sure you ask for permission from the mentors before working on an issue as there might be other people who could already be working on that issue. A simple message such as</p>
<div class="highlight"><pre><span></span>Hey, I want to work on this issue. Is it already assigned?
</pre></div>
<p>will do the work. </p>
<h3>2.2 Wait for the response</h3>
<p>You have to understand that people live in various parts of the world and have different timelines. They might be having a holiday which might be a working day in your country. Also, they might be working on multiple projects. You must take care of all the factors and should not keep messaging in order to get a reply. </p>
<h3>2.3 Make your changes</h3>
<p>Once you get the approval from a mentor, go ahead and make the changes as per the issue. <strong>Don't make any unnecessary changes.</strong> Examples are
- Introducing new lines.
- Removing and adding spaces.
- Changes other than the assigned issue.
- Changing the workflow of the project.</p>
<p>These should be evaluated first before making a commit.</p>
<h2>3. Getting Stuck</h2>
<p>As a newcomer, it is obvious that you might get stuck at a place where you might not understand what is going wrong. <strong>Don't panic</strong> .Others might have also faced similar issues.</p>
<h3>3.1 Checking versions</h3>
<p>If these are the cases, follow the README in the repo to correct your mistakes. Make sure you are on the right version as that told in the repository.
- There might be certain dependencies which only work on a specific Operating System.
- Certain functions could be deprecated or renamed in newer versions of a library.
- The programming language might follow newer syntax rules as compared to previous versions.</p>
<h3>3.2 Searching for a solution</h3>
<p>Others who got the same problem could have asked on the web for a solution. In most cases, you might get the remedy on <em>StackOverflow</em>. A good practice is to try to solve the problem and if you are unable to, copy the exact error in <em>Google</em> and look for the solutions.</p>
<h3>3.3 Asking the mentors</h3>
<p>This should be the last resort and make sure you do this only after you have followed the above two steps and done an extensive research but are still unable to get a remedy for your problem. Generate a message containing
- The problem you are facing.
- What solutions you have tried.
- Links to solutions you have tried.
- Relevant screenshots.</p>
<p><strong>Value their time.</strong> Don't ask irrelevant questions as they are giving you, their time by answering your query. It can be a bit annoying for the reviewers if you ask unnecessary questions which might already be on Google.</p>
<h2>4. Pull requests</h2>
<p>When creating a Pull Request (<em>also called a PR</em>), there are certain practices which give better results.</p>
<h3>4.1 Add your files</h3>
<p>If you are working on a single issue, you can use</p>
<div class="highlight"><pre><span></span>git add .
</pre></div>
<p>However, this is not suggested for multiple issues and you should only add the desired files for which changes were <em>required</em> using</p>
<div class="highlight"><pre><span></span>git add filename.py
</pre></div>
<h3>4.2 Squashing your commits</h3>
<p><strong>One PR needs one commit</strong>. Squash all your commits into a single commit.</p>
<p>Remember, Branching is the key to avoid all the commit problems.</p>
<div class="highlight"><pre><span></span>git checkout <branch name>
</pre></div>
<p>Merging 5 commits to a single commit.</p>
<div class="highlight"><pre><span></span>git rebase -i <branch name>~5 <branch name>
</pre></div>
<p>At the Interactive screen, choose fixup for commit 2 / 3 / 4 / 5.</p>
<div class="highlight"><pre><span></span>git push -u origin <branch name>
</pre></div>
<p><strong>Commit Related issues?</strong> If you have any issues regarding commits, go ahead and see this <a href="https://channelcs.github.io/wrong-files-added-in-commit.html">post</a>.</p>
<h3>4.3 Generating a Pull Request</h3>
<p>Separate PRs should be generated for different issues. If not, they get mixed and create a ruckus when everything is done on the master branch.
In order to create better PRs, it is recommended that you should create PRs on a branch which could be named as <code>solves-issue-21</code>. This not only helps in working on multiple issues simultaneously but also makes the collaborator at the other end, understand what the PR does.</p>
<h3>4.4 Creating a new branch</h3>
<ol>
<li>
<p>Add a new branch for pushing our changes to an issue.</p>
<div class="highlight"><pre><span></span>git checkout -b <branch-name>
</pre></div>
</li>
<li>
<p>If required, rebase your branch even to master by following the rebase <a href="#rebase">steps</a></p>
</li>
<li>
<p>Push the changes to your repo.</p>
<div class="highlight"><pre><span></span>git push origin <branch-name>
</pre></div>
</li>
</ol>
<h2>5.Rebasing your repository</h2>
<h3>5.1 What is a Rebase?</h3>
<p>Rebasing is changing the base of your branch from one commit to another making it appear as if you'd created your branch from a different commit. </p>
<h3>5.2 Why is it needed?</h3>
<ul>
<li>The forked repository is few commits behind.</li>
<li>Newly created branch is not even with the master branch.</li>
</ul>
<h3>5.3 How to rebase?<a name='rebase'></a></h3>
<ol>
<li>
<p>Check current configured forked repository</p>
<div class="highlight"><pre><span></span>git remote -v
</pre></div>
</li>
<li>
<p>Set new remote repository that will be synced</p>
<div class="highlight"><pre><span></span>git remote add upstream <original-github-repo-link>
</pre></div>
</li>
<li>
<p>Check new upstream repository</p>
<div class="highlight"><pre><span></span>git remote -v
</pre></div>
</li>
<li>
<p>Fetch the original Github repository</p>
<div class="highlight"><pre><span></span>git fetch upstream
</pre></div>
</li>
<li>
<p>Rebase the commits</p>
<div class="highlight"><pre><span></span>git rebase -i upstream/master
</pre></div>
</li>
<li>
<p>Push the changes </p>
<div class="highlight"><pre><span></span>git push -f
</pre></div>
</li>
<li>
<p>Rebase commits against a specific branch and then proceed with Step 6</p>
<div class="highlight"><pre><span></span>git rebase -i <branch-name>
</pre></div>
</li>
<li>
<p>Rebase commits against a specific node and then proceed with Step 6</p>
<div class="highlight"><pre><span></span>git rebase -i HEAD~<commit-number>
</pre></div>
</li>
</ol>
<h2>6. List of open-source competitions and Internships.</h2>
<ul>
<li><a href="https://wiki.mozilla.org/Security/Automation/Winter_Of_Security_2016">Mozilla Winter of Security</a> </li>
<li><a href="https://www.gnome.org/outreachy/">Outreachy</a></li>
<li><a href="http://railsgirlssummerofcode.org/">RGSOC</a> </li>
<li><a href="https://trac.torproject.org/projects/tor/wiki/org/TorSoP">TOR Summer of Privacy</a> </li>
<li><a href="https://www.google-melange.com/gci/homepage/google/gci2014">GCI</a></li>
<li><a href="https://developers.google.com/open-source/gsoc/">GSOC</a> </li>
<li><a href="https://wiki.opendaylight.org/view/Interns">OpenDaylight summer internship program</a> </li>
<li><a href="https://www.dataone.org/internships">DataONE Summer Internship Program</a> </li>
<li><a href="http://www.fsf.org/volunteer/internships">Free Software Foundation Internship</a></li>
<li><a href="http://rada.re/r/rsoc.html">Radare Summer of Code</a> </li>
<li><a href="https://summer.haskell.org/">Summer of Haskell</a></li>
<li><a href="https://open.segment.com/fellowship">Segment Open Fellowship</a></li>
<li><a href="http://2017.summerofcode.be/">Open Summer of Code</a></li>
<li><a href="http://lab.codingblocks.com/boss/">Bountiful Open Source Summer- BOSS</a> </li>
<li><a href="https://hacktoberfest.digitalocean.com/">Hacktoberfest</a></li>
<li><a href="https://halite.io/">Halite AI Bot Challenge</a></li>
<li><a href="http://sigmm.org/Resources/software/ossc">ACM MM Open Source Software Competition</a> </li>
</ul>
<h2>7. Sources</h2>
<ul>
<li><a href="https://help.github.com/articles/about-git-rebase/">Github Help</a></li>
<li><a href="https://www.hackerearth.com/getstarted-opensource/">How to get started with Open Source</a></li>
<li><a href="https://opensource.com/life/15/2/developers-guide-getting-involved-open-source">A developer's guide to getting into open source</a></li>
<li><a href="http://eulercoder.me/2017/07/getting-started-open-source/">Getting Started with Open Source</a>
-<a href="https://www.linuxfoundation.org/resources/open-source-guides/starting-open-source-project/">Starting an Open Source Project</a></li>
<li><a href="https://www.smashingmagazine.com/2013/01/starting-an-open-source-project/">How To Start An Open-Source Project</a></li>
<li><a href="https://medium.freecodecamp.org/how-to-start-an-open-source-project-in-new-years-945bad8800d7">How to start an Open Source project</a></li>
<li><a href="https://www.firsttimersonly.com/">Welcome! Let’s do some open source!</a></li>
<li><a href="https://opensource.guide/">Open Source Guides</a></li>
<li><a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">Git Rebasing </a></li>
<li><a href="https://github.com/tapasweni-pathak/SOC-Programs/blob/master/README.md">SOC-Programs</a></li>
</ul></div>
<hr>
<h2>Comments</h2>
<div id="disqus_thread"></div>
<script type="text/javascript">
var disqus_shortname = 'channelcsgit';
var disqus_title = 'Best practices in a collaborative environment';
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'https://' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
</div>
</div>
<div class="span3">
<div class="well" style="padding: 8px 0; background-color: #FBFBFB;">
<ul class="nav nav-list">
<li class="nav-header">
Site
</li>
<li><a href="/archives.html">Archives</a>
<li><a href="/tags.html">Tags</a>
<li><a href="/feeds/all.atom.xml" rel="alternate">Atom feed</a></li>
</ul>
</div>
<div class="well" style="padding: 8px 0; background-color: #FBFBFB;">
<ul class="nav nav-list">
<li class="nav-header">
Categories
</li>
<li><a href="/category/audio-processing.html">Audio Processing</a></li>
<li><a href="/category/deep-learning.html">Deep Learning</a></li>
<li><a href="/category/docs.html">Docs</a></li>
<li><a href="/category/github.html">Github</a></li>
<li><a href="/category/main.html">main</a></li>
<li><a href="/category/outreachy.html">Outreachy</a></li>
</ul>
</div>
<div class="well" style="padding: 8px 0; background-color: #FBFBFB;">
<ul class="nav nav-list">
<li class="nav-header">
Links
</li>
<li><a href="http://github.com/channelCS">Github</a></li>
<li><a href="http://github.com/Deeplearn-lab">Deeplearn-lab</a></li>
</ul>
</div>
</div>
</div> </div>
<footer>
<br />
<p><a href="">channelCS</a> © channelCS 2018</p>
</footer>
</div> <!-- /container -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script src="/theme/bootstrap-collapse.js"></script>
</body>
</html>