-
Notifications
You must be signed in to change notification settings - Fork 16
/
open_source.theory.txt
390 lines (335 loc) · 26.4 KB
/
open_source.theory.txt
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
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
OPEN_SOURCE
/=+===============================+=\
/ : : \
)==: DOCUMENTATION :==(
\ :_______________________________: /
\=+===============================+=/
DOCUMENTATION ==> # - scopes: reference, guide, tutorial
# - formats: text, video
# - move big sections into separate files
# - lots of links
# - use simple language
# - README.md is most important
EXAMPLES ==> # - importance of examples, demos, screenshots and screencasts
# - have code snippets of documentation also in examples/ directory
# - should be executable and tested
# - can use ```diff block if makes sense to show as a diff (before/after adding usage)
README.MD SECTIONS ==> # - title
# - logo
# - badges
# - should include platform support
# - link to website
# - link to articles
# - potential deprecation status
# - catchphrase
# - use emojis
# - sales pitch / how this will help you (why)
# - avoid writing down definitions
# - features (how)
# - synopsis example / screenshot / screencast
# - can be an example session of Node REPL / Bash shell
# - should be understandable without screenshots for accessibility
# - use cases
# - table of contents (if big) (what)
# - demo / online playground
# - install / prerequisites / get started
# - including updating if needs be
# - usage
# - API/methods/options
# - comparison with competing projects
# - benchmarks
# - who uses this project
# - "Related" / "See also"
# - how to file bugs / ask questions / send feedback / send feature requests
# - how to contribute
# - code of conduct
# - roadmap
# - contributors list
# - with avatar, links
# - link to AUTHORS file
# - changelog
/=+===============================+=\
/ : : \
)==: COMMUNICATION :==(
\ :_______________________________: /
\=+===============================+=/
COMMUNICATION ==> # - Slack/Gitter
# - keep discussions public
# - answer within 48 hours, preferably 24
# - especially for PRs
# - avoid negative or rude tone
REJECTIONS ==> # - reject issues/PRs instead of leaving them open
# - thank even if rejected
# - explain the rejection
# - link to guidelines or project scope document
CODE OF CONDUCT ==> # - online and offline
# - communicate:
# - in top directory file named CODE_OF_CONDUCT.md
# - how it is enforced
# - how to report
# - must allow anonymous reporting
# - enforce:
# - responses: private warn < public warn < asking for apology < temporary ban < total ban
# - in all cases, edit|remove content
# - should investigate first
# - e.g. read previous comments and activity
# - examples:
# - https://www.contributor-covenant.org
# - https://js.foundation/community/code-of-conduct
/=+===============================+=\
/ : : \
)==: CONTRIBUTIONS :==(
\ :_______________________________: /
\=+===============================+=/
TYPES ==> # - communicate which types of contributions are the most welcomed
# - can be:
# - code (refactoring, PR/new feature, bug/issue, tests, porting, devOps, plugins)
# - code review
# - documentation (review existing or new)
# - translation
# - design (e.g. logo)
# - promotion: online, offline (events)
# - feature suggestions
# - bug reports
# - answering questions
# - engage community (e.g. chat moderation)
# - see all-contributors for standard name and emojis
CONSTRAINTS ==> # - project goals and scope
# - testing
# - adding documentation
# - non-functional requirements: compatibility, performance, etc.
# - coding style
# - commit message convention
# - commit squashing policy
PROCESS ==> # - how to file issue/PR
# - descriptive title
# - for issues:
# - reproducible code
# - environment
# - not mix two different issues/PRs
# - link to each other with #NUM
# - labels
# - whether should file issue before submitting PR to outline design and whether it will be accepted
# - security issues should be directly emailed, not open a public issue
# - which channel to use
# - e.g. Gitter for issues understanding how to use, GitHub issues for bug reports and feature requests
# - code review process
# - how to setup dev environment
COMMUNICATING ==> # - should communicate process
# - GitHub PR/issue templates
# - CONTRIBUTING.md
# - should be in top directory, to be recognized by GitHub
# - explain why they should read that document (i.e. will save everyone's time)
# - BUGS.md: same but for issues
# - use checklists:
# - use markdown [ ]
# - as small as possible while still covering everything
ENFORCING ==> # - Git hooks
# - tasks runner like Gulp
# - CI
# - GitHub status checks
ATTRACTING ==> # - communicate contributions are welcome
# - start answering issues by asking if they can PR, while explaining we welcome contributions
# - on project website add "Edit" button that redirects to GitHub edit button
# - submit issues to:
# - https://www.codetriage.com (issues labeling/triage)
# - https://24pullrequests.com
REWARDING ==> # - thank:
# - in advance in CONTRIBUTING.md
# - in issue/PR
# - in public, e.g. Twitter, blog post, etc.
# - in changelog
# - show list of names/avatars of all contributors in:
# - CONTRIBUTORS, AUTHORS or humans.txt file
# - team page on website
FIRST TIMERS ==> # - starter issues:
# - label easy GitHub issues with "good first issue", "first-timers-only" and "help wanted"
# - write that some issues are reserved for first timers and link to them
# - add a to-do list
# - should start by "claim this issue"
# - promote on http://up-for-grabs.net
# - explain how to do a PR:
# - https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github
# - playgrounds for first PR:
# - https://github.com/firstcontributions/first-contributions
# - https://github.com/Syknapse/Contribute-To-This-Project
# - first-timers-bot
/=+===============================+=\
/ : : \
)==: PROJECT MANAGEMENT :==(
\ :_______________________________: /
\=+===============================+=/
GITHUB ORGANIZATION ==> #If lots of contributors and need different permissions
ROADMAPS ==> # - ROADMAP.md
# - content:
# - start with welcome message
# - short-term, mid-term, long-term
# - links to PR/issues
# - overall project goals and scope
# - formats:
# - flat list / kanban
# - GitHub milestones
# - agile board
# - GitHub project tab
/=+===============================+=\
/ : : \
)==: RELEASES :==(
\ :_______________________________: /
\=+===============================+=/
RELEASING ==> # - changelog
# - git tag
# - GitHub release
# - promote on social media
DEPRECATING ==> # - prepend description with DEPRECATED
# - make repo read-only
# - point to alternative project
# - npm deprecate
/=+===============================+=\
/ : : \
)==: PROMOTION :==(
\ :_______________________________: /
\=+===============================+=/
PROMOTION ==> # - time to post:
# - traffic is during work hours, i.e. before start work US, i.e. 3pm
# - Wednesday is best day, but Friday and weekends are bad days, i.e. prefer Tuesday to
# keep it up for several days
# - channels should promote each other
# - e.g. promote my Twitter and Medium on READMEs
# - add "Star" buttons on project website
# - offline events:
# - contributors code sprints
# - conference talks
# - ask users to promote on issue/PR after it is solved
# - saythanks.io or alternative. Goals:
# - engaging users (answer them)
# - promote as a Testimony section (ask for permission first, ideally as a checkbox)
# - promote on CV website
/=+===============================+=\
/ : : \
)==: NAMING :==(
\ :_______________________________: /
\=+===============================+=/
NAMING ==> # - should be the same for GitHub, package manager, domain name and in-code
# - should be descriptive, i.e. indicate what module does:
# - better SEO
# - more likely to be clicked on
TRADEMARKS ==> # - definition:
# - anything showing source/origin/identity
# - only within a specific context
# - can be:
# - name
# - logo
# - "trade dress": trademark applied to colors/designs/look&feel
# - differences:
# - copyright: implementation
# - patent: logic/algorithm/idea
# - "service mark": like trademark but for a service instead of a product
# - cannot be similar sounding/looking, unless common words
# - i.e. prefer unusual words
# - name (not logo) should always:
# - be capitalized or all-uppercased to differentiate from surrounding text
# - be not combined/hyphenated with another word
# - be not abbreviated
# - use same spelling
# - not be pluralized
# - not be translated
# - used as a noun nor verb (but adjective or geround is ok)
# - symbols:
# - tm: registered or not
# - (R): registered
# - neither is required, it just advertise it
# - registering:
# - unregistered trademarks still work but harder to enforce
# - country/countries-specific
# - bureaucratic and expensive
# - must pay renewal fees every 10 years
# - can be made unregistered if project not used anymore
# - can transfer ownership to umbrella org like Linux fundation so they pay for trademarks and administrative things
# - by default fully restricted usage without permission except "nominative use":
# - when using name is necessary for understanding
# - e.g. "certification for {name}"
# - examples:
# - http://modeltrademarkguidelines.org/index.php/OSS_Trademark_Policies
# - http://modeltrademarkguidelines.org/index.php/Model_Trademark_Guidelines
MODEL TRADEMARK GUIDELINES ==> # - for logo, name and trade dress
# - can exclude specific ones so they are fully restricted
# - allow any use except:
# - if confuse about origin
# - e.g. saying it is official website or endorsed
# - if confuse about content
# - e.g. saying distribution {name} but not sating there are modifications
# - bundling our main code with another main code. However this is ok:
# - distributing modified version
# - distributing another main code but not bundled
# - linking/libraries
# - for-profit user groups or goods
# - for domain names (for name)
# - not full website (for trade dress)
# - must be kept as is (for logo)
# - no modification nor combining with another logo
# - scaling and black&white is ok
# - should add:
# - (R) or tm next to first and most prominent name/logo on a page
# - footnote notice about trademark
/=+===============================+=\
/ : : \
)==: ANALYTICS :==(
\ :_______________________________: /
\=+===============================+=/
METRICS ==> # - user surveys:
# - integrate with documentation:
# - poll widgets inside online doc
# - tutorials with optional feedback steps
# - survey results publicly available (open data)
# - anonymous
# - AARRR is a funnel for users that:
# - Acquisition: see the project
# - Activation: use the project once
# - Retention: use the project over time
# (- Referral: tell other users)
# - Revenue: pay
MONITORING ==> # - RSS feed on StackOverflow tags
/=+===============================+=\
/ : : \
)==: OTHERS :==(
\ :_______________________________: /
\=+===============================+=/
GITHUB ==> # - repo named ".github" for an organization:
# - files shown in all repos unless they have that file
# - only in GitHub not in git
# - only for root /docs, /.github, CODE_OF_CONDUCT, CONTRIBUTING, README or issues/PR templates
# - issues/PR templates:
# - done from "features" tab
# - can be committed as YAML to .github/
# - can divide between bugs, feature requests, PRs or custom categories
# - has:
# - title placeholder
# - content placeholder
# - labels
# - assignees
# - tags:
# - first relevant and differentiating ones
# - then from https://github.com/topics:
# - 3d ajax algorithm amphp android angular ansible api arduino aspnet atom awesome aws azure babel bash
# bitcoin bootstrap bot c chrome chrome-extension cli clojure code-quality code-review compiler
# continuous-integration covid-19 cryptocurrency cpp crystal csharp css data-structures data-visualization
# database deep-learning dependency-management deployment django docker documentation dotnet electron
# elixir emacs ember emoji emulator eslint ethereum express firebase firefox flask font framework frontend
# game-engine git github-api go google gradle graphql gulp hacktoberfest haskell homebrew homebridge html
# http icon-font ios ipfs java javascript jekyll jquery json julia jupyter-notebook koa kotlin kubernetes
# laravel latex library linux localization lua machine-learning macos markdown mastodon material-design
# matlab maven minecraft mobile monero mongodb mongoose monitoring mvvmcross mysql nativescript nim nlp
# nodejs nosql npm objective-c opengl operating-system p2p package-manager parsing perl phaser php pico-8
# pixel-art postgresql project-management publishing pwa python qt r rails raspberry-pi ratchet react
# react-native reactiveui redux rest-api ruby rust sass scala scikit-learn sdn security server serverless
# shell sketch spacevim spring-boot sql storybook swift symfony telegram tensorflow terminal terraform
# testing twitter typescript ubuntu unity unreal-engine vagrant vim virtual-reality vue wagtail
# web-components webapp webpack windows wordplate wordpress xamarin xml
PLUGINS ==> # - put into separate repositories
# - create generic test suite
# - create doc on how to create new ones
# - create specific tags so they are easy to find on npm
# - naming convention, e.g. autoserver-format-yaml, so they can be require()'d
# - encourage them as a way to reduce workload of core repo and attract contributors