-
Notifications
You must be signed in to change notification settings - Fork 0
/
development_practices
189 lines (129 loc) · 6.09 KB
/
development_practices
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
UTC20151104
These development practices largely follow the Urbit Contribution
Guidelines, with additional protocols to support multiple
projects. They are designed to scale with low administrative overhead
from small to moderately sized codebases and project teams.
ToC:
I. General Principles
II. Workflows
III. Discussion
IV. Tools
I. General Principles:
1. Keep IXT maintained repos as few as possible, bias contributions
instead to upstream maintainers. Forks of non-organic repos are not
considered to be under maintanence for this purpose.
2. IXT repos, whether native or external forks, are never pushed to
directly. All code changes are the result of a pull request from a
development fork (to which the contributor has first-class push
access) to the IXT repo test branch, then a PR from test to master (as
conditions dictate).
3. The canonical origin for IXT developed projects is the IXT repo
origin branch. It is the responsibility of the project administrator
to keep the IXT origin updated (e.g. if an external project's origin
changes), so that contributor forks may pull from the correct
environment to develop against.
4. Contributor pull requests are preferred over granting collaborator
status, to preserve the PR-only update of IXT canonical repos and
allow contributors a separate public record of their work.
5. Aside from assignation by IXT project admins, outside contributors
to IXT repos are considered team members, and held to the same
workflow standards.
II. Workflows
Three main project structures: Organic, External, Symbiotic.
Organic: Projects conceived and begun entirely by Ix Technology the
corporate entity, or for which ownership has been transferred to the
company as if that criterion held.
Workflow:
1. Project admin creates IxT project repo with two branches - master
and test.
2. Assign Team(s). Team members fork IxT repo, create personal branch
dev
3. Members develop on personal dev branches, push to personal remote
forks
4. Members submit pull requests from personal dev to IxT test.
5. Project admin merges pull request
6. Project admin submits pull request from IxT test to master, merges.
7. Team members pull IxT master to synchronize with latest production
code.
External: Projects begun outside of Ix Technology, by entities not
currently associated with the company, to which Ix Technology wishes
to contribute.
Workflow:
1. Project admin creates IXT fork of external repo, adds branch test
if not present.
2 - 5. Workflow continues as per steps 2 - 5 for Organic projects.
6. Project admin submits pull request from IXT test branch to external
project, following their PR guidelines.
7. Project admin pulls new canonical image from external repo,
team members resynchronize development forks from IXT fork.
Symbiotic: Projects begun outside of Ix Technology by entities
currently associated with the company, who wish to retain independent
ownership.
1 - 7. As per steps 1-7 for External projects, with the exception that
the owner of the repo may bypass submitting pull requests to the IXT
fork, and follow their own practices in maintaining their codebase. It
is recommended that development still follow a dev->test->master merge
flow, marked by public pull requests, to bolster transparency and
afford appropriate intervals to incorporate IXT and external
contributions.
III. Discussion
It is critical that feature requests, design debates, and other
comments on IxTech and IxTech involved projects be by default public
and later searchable. Development, particularly open source
development, only flourishes when the meta-data of discussion is
transparent and eidetically remembered. The following establishes
where such discourse takes place by default, to facilitate these
qualities.
To the project categories in section II, consider the additional
discussion category "unspecified":
Unspecified: Commentary on Ix Technology the company, the behavior of
its members and associates, future project ideas, and other
non-project specific topics.
Location:
Default to discussion on the dev@ixtech.net mailing list. Mirror
e-mail to a local mail client for off-line viewing/storage
redundancy. The ixtechnology repository "scratchpad" may also be used
for strictly project-oriented discussion about codebases that do not
yet exist under IxTech's jurisdiction.
Organic: Issues concerning existing individual projects entirely
within the IxTech fold.
Location:
The tracking system associated with the ixtechnology canonical
repo. Mirror track system issues to local storage.
External: Two cases - i. Commentary on the project itself.
ii. Intra-IxTech discussion of IxTech contributions to an external
project.
Location:
i. By default, commentary on external projects should take via the
project's native mechanism, then mirrored for Ix Technology's own
recollection. If a native converstaion becomes too IxTech specific, it
can always be converted to case ii.
ii. The tracker system associated with the ixtechnology canonical fork
of the external project, mirrored to local storage.
Symbiotic: Identical to External, aside from the familiarity of the
personages involved.
Location:
i. As per External-i.
ii. As per External-ii.
IV. Tools
The above practices assume fairly generic development tools, but are
designed with git or a git compatible distributed version control
system and associated tracker program in mind.
Tool resources:
DVCS:
git: http://git-scm.com/
Local mail client:
mutt: http://www.mutt.org/
GitHub cli remote repo creation, forking, pull requests:
hub: https://hub.github.com/
Do not feel the need to alias "git" to "hub" as per the documentation;
experience suggests this only causes confusion in the long run.
GitHub cli Issues tracker system utility:
ghi: https://github.com/stephencelis/ghi
Mirror GitHub issues to view offline, but not otherwise manage:
offline-issues: https://github.com/stephencelis/ghi
Other suggestions - especially for local issue management - welcome.
Project idea: combine offline-issues and ghi to allow
offline/asynchronous cli GitHub Issues management with local
mirroring, ideally in a language with a less massive dependency
footprint than Node.js or Ruby.