You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/blog/entries/2023-03-24-community-contributions/contents.lr
+109-50
Original file line number
Diff line number
Diff line change
@@ -10,82 +10,141 @@ author: sara
10
10
pub_date: 2023-03-24
11
11
---
12
12
body:
13
-
Different open source communities work differently and so everyone may arrive at Creative Commons' projects with their own set of individual expectations. Someone might expect to directly submit a Pull Request to a project without an Issue. Or they may submit an Issue and then immediately an associated Pull Request. At Creative Commons we have a process we hope to follow so there's a chance for consideration, community participation, and discussion along the way. Where we make collaborative, well documented, and informed work more possible!
14
13
15
-
Things usually begin with an idea for new functionality, new/revised documentation, or an encountered error of sorts. That idea or error is then captured as a GitHub Issue used to describe its details. Think of this as the Abstract that comes before the Implementation.
16
-
17
-
It's important to first look through all the existing Issues, including ones that have been Closed to determine if someone else has already made an overlapping Issue. If they have, it's best to add any new information you've discovered or thought of as a comment (or series of comments) to that Issue, rather than create a new one.
18
-
19
-
Errors (often referred to as Bugs) should be verified, and reproducible if possible. Things like screenshots, steps to reproduce, a video, and environment details are all incredibly helpful for others when they want to review the error. All that information is gathered and placed in a succinct, but detailed Issue on the associated repository. It's worth noting that the documented Issue alone is a valued contribution. It will provide guidance and documentation for whomever works on resolving or implementing it, so it's just as important as the eventual code that will be written. That means it should be done well, because the better an Issue describes an error and provides a clear way to reproduce it the easier it will be for anyone to address it.
20
-
21
-
Functionality and Feature proposals are often a little more involved. Errors are some aberration in the existing expectations or functionality of the codebase's state, but new/changed functionality or features introduce larger planning considerations. They have to take into account the current state of things and the proposed future state they're introducing as an Issue. This is an exercise in communication and description first and foremost, and that means that having a detailed writeup, wireframes, mockups, and evidence to support the proposal is vital to its success. Where Errors might be able to consider a more isolated set of consequences to fixing something, introducing new features/functionality may have unintended side effects, it may require multiple parts of the codebase to be changed or altered. All of these larger picture considerations should be taken into account and addressed within the Issue. One should expect that a Feature Issue may on average take longer to introduce, and longer to adequately document in a clear and concise way to get the point across to the rest of the community.
22
-
23
-
Documentation can always use improvements whether within code comments, a project's README.md, or associated documentation. These would largely be considered a "Feature Issue" technically but it's worth pointing them out separately because they're as important, if not more so, than fixing errors or adding codebase level functionality. Good documentation makes the project strong and the community more informed. Improvements here should document where there's a gap or where revisions are needed, and how they should be corrected.
24
-
25
-
Whether an Error or Feature/functionality Issue, once it's been submitted, in accordance with the [Contribution Guidelines](https://opensource.creativecommons.org/contributing-code/), it will move to a status of "awaiting triage". This means that it is waiting to be reviewed by one of the core codebase contributors. While it's in this state no implementation work should be done (no PRs, no code work to add or correct the behavior). An Issue submitted is largely the start of a process, and a conversation. Core contributors will review the Issue and see if it adequately describes its appropriate details, and if its objectives fit within the larger pattern and goals of the codebase itself. It's entirely possible that a well thought through Feature Issue that adds some new menu functionality is in isolation a good idea, but that it doesn't fit within the goals of the project in question and won't move forward. And that's OK, even if an Issue doesn't move forward it can now stand as documentation for the community on what won't be worked on at this time, which is just as important as what will. It's a contribution whether it moves forward or not, so long as it describes itself well enough.
14
+
Different open source communities work differently and so everyone may arrive
15
+
at Creative Commons' projects with their own set of individual expectations.
16
+
Someone might expect to directly submit a Pull Request to a project without an
17
+
Issue. Or they may submit an Issue and then immediately an associated Pull
18
+
Request. At Creative Commons we have a process we hope to follow so there's a
19
+
chance for consideration, community participation, and discussion along the
20
+
way. Where we make collaborative, well documented, and informed work more
21
+
possible!
22
+
23
+
Things usually begin with an idea for new functionality, new/revised
24
+
documentation, or an encountered error of sorts. That idea or error is then
25
+
captured as a GitHub Issue used to describe its details. Think of this as the
26
+
Abstract that comes before the Implementation.
27
+
28
+
It's important to first look through all the existing Issues, including ones
29
+
that have been Closed to determine if someone else has already made an
30
+
overlapping Issue. If they have, it's best to add any new information you've
31
+
discovered or thought of as a comment (or series of comments) to that Issue,
32
+
rather than create a new one.
33
+
34
+
Errors (often referred to as Bugs) should be verified, and reproducible if
35
+
possible. Things like screenshots, steps to reproduce, a video, and environment
36
+
details are all incredibly helpful for others when they want to review the
37
+
error. All that information is gathered and placed in a succinct, but detailed
38
+
Issue on the associated repository. It's worth noting that the documented Issue
39
+
alone is a valued contribution. It will provide guidance and documentation for
40
+
whomever works on resolving or implementing it, so it's just as important as
41
+
the eventual code that will be written. That means it should be done well,
42
+
because the better an Issue describes an error and provides a clear way to
43
+
reproduce it the easier it will be for anyone to address it.
44
+
45
+
Functionality and Feature proposals are often a little more involved. Errors
46
+
are some aberration in the existing expectations or functionality of the
47
+
codebase's state, but new/changed functionality or features introduce larger
48
+
planning considerations. They have to take into account the current state of
49
+
things and the proposed future state they're introducing as an Issue. This is
50
+
an exercise in communication and description first and foremost, and that means
51
+
that having a detailed writeup, wireframes, mockups, and evidence to support
52
+
the proposal is vital to its success. Where Errors might be able to consider a
53
+
more isolated set of consequences to fixing something, introducing new
54
+
features/functionality may have unintended side effects, it may require
55
+
multiple parts of the codebase to be changed or altered. All of these larger
56
+
picture considerations should be taken into account and addressed within the
57
+
Issue. One should expect that a Feature Issue may on average take longer to
58
+
introduce, and longer to adequately document in a clear and concise way to get
59
+
the point across to the rest of the community.
60
+
61
+
Documentation can always use improvements whether within code comments, a
62
+
project's README.md, or associated documentation. These would largely be
63
+
considered a "Feature Issue" technically but it's worth pointing them out
64
+
separately because they're as important, if not more so, than fixing errors or
65
+
adding codebase level functionality. Good documentation makes the project
66
+
strong and the community more informed. Improvements here should document where
67
+
there's a gap or where revisions are needed, and how they should be corrected.
68
+
69
+
Whether an Error or Feature/functionality Issue, once it's been submitted, in
70
+
accordance with the [Contribution
71
+
Guidelines](https://opensource.creativecommons.org/contributing-code/), it will
72
+
move to a status of "awaiting triage". This means that it is waiting to be
73
+
reviewed by one of the core codebase contributors. While it's in this state no
74
+
implementation work should be done (no PRs, no code work to add or correct the
75
+
behavior). An Issue submitted is largely the start of a process, and a
76
+
conversation. Core contributors will review the Issue and see if it adequately
77
+
describes its appropriate details, and if its objectives fit within the larger
78
+
pattern and goals of the codebase itself. It's entirely possible that a well
79
+
thought through Feature Issue that adds some new menu functionality is in
80
+
isolation a good idea, but that it doesn't fit within the goals of the project
81
+
in question and won't move forward. And that's OK, even if an Issue doesn't
82
+
move forward it can now stand as documentation for the community on what won't
83
+
be worked on at this time, which is just as important as what will. It's a
84
+
contribution whether it moves forward or not, so long as it describes itself
85
+
well enough.
26
86
27
87
If this happens, the Issue will be moved to a status of "discarded", and will
28
-
be closed with a comment explaining why. The other reason an Issue might be
29
-
moved to "discarded" is that it duplicates the work in another Issue, which
30
-
is why it's important to first check all the existing Issues prior to
31
-
submitting a new one.
88
+
be closed with a comment explaining why. The other reason an Issue might be
89
+
moved to "discarded" is that it duplicates the work in another Issue, which is
90
+
why it's important to first check all the existing Issues prior to submitting a
91
+
new one.
32
92
33
-
Sometimes an Issue might describe something much broader than can be easily
93
+
Sometimes an Issue might describe something much broader than can be easily
34
94
contained within itself and may be converted to a status of "discussion". This
35
-
means that the Issue should spark a larger conversation within the community
36
-
to consider all the angles of abstract, and possibly split the idea up into
37
-
more manageable pieces across multiple Issues. Other outcomes might be a
38
-
discussion that realizes that while the idea is sound, it's not implementable
39
-
at this time and won't move forward.
40
-
41
-
Some Issues are solid ideas, but they are not something that can move forward
42
-
until work on other Issues is completed first. As such they tend to move to a
95
+
means that the Issue should spark a larger conversation within the community to
96
+
consider all the angles of abstract, and possibly split the idea up into more
97
+
manageable pieces across multiple Issues. Other outcomes might be a discussion
98
+
that realizes that while the idea is sound, it's not implementable at this time
99
+
and won't move forward.
100
+
101
+
Some Issues are solid ideas, but they are not something that can move forward
102
+
until work on other Issues is completed first. As such they tend to move to a
43
103
status of "blocked". They'll sit in that state until they're unblocked and the
44
-
work can happen.
104
+
work can happen.
45
105
46
106
If an Issue seems like it doesn't have enough information to determine what to
47
-
do with it, then it will likely move to a status of "ticket work required" and a comment will usually be left describing what needs to be worked on.
107
+
do with it, then it will likely move to a status of "ticket work required" and
108
+
a comment will usually be left describing what needs to be worked on.
48
109
49
110
Remember, an Issue is a form of documentation, and in a way it's a
50
-
conversation, and that means that until it moves forward it's very much a
51
-
work in progress.
111
+
conversation, and that means that until it moves forward it's very much a work
112
+
in progress.
52
113
53
114
If an Issue passes through this period as implementable, then it'll move to a
54
-
status of "ready for work". This is the point at which it can be implemented,
55
-
and a contributor can submit a Pull Request addressing it. (See the
56
-
[Repository Labels Status section](https://opensource.creativecommons.org/co
57
-
ntributing-code/repo-labels/#status) for more information)
115
+
status of "ready for work". This is the point at which it can be implemented,
116
+
and a contributor can submit a Pull Request addressing it. (See the [Repository
117
+
Labels Status section](https://opensource.creativecommons.org/co
118
+
ntributing-code/repo-labels/#status) for more information)
58
119
59
-
During this process it is worth noting that there will be multiple types of
60
-
contribution. For example:
120
+
During this process it is worth noting that there will be multiple types of
121
+
contribution. For example:
61
122
62
123
* The Issue itself is a contribution
63
124
* Comments on the Issue from the community refining it are each contributions
64
125
* Someone's comment on the Issue helping another person sort out why the Error
65
-
is occurring is a contribution.
126
+
is occurring is a contribution.
66
127
* Someone finding another related Issue and linking it as relevant to that
67
-
Issue is a contribution.
128
+
Issue is a contribution.
68
129
69
130
All of these contributions occurred before a Pull Request was ever initiated.
70
-
Once an Issue enters a status of "ready for work" someone who has indicated
71
-
interest on that Issue will be assigned to it and can then fork the
72
-
repository, make a branch to work within, and once settled submit a Pull
73
-
Request. That process alone may involve several contributions as well, such
74
-
as:
131
+
Once an Issue enters a status of "ready for work" someone who has indicated
132
+
interest on that Issue will be assigned to it and can then fork the repository,
133
+
make a branch to work within, and once settled submit a Pull Request. That
134
+
process alone may involve several contributions as well, such as:
75
135
76
136
* The code work encounters a problem, someone asks for assistance within their
77
-
draft PR, and several members offer help as comments.
137
+
draft PR, and several members offer help as comments.
78
138
* Someone reviews the final PR and leaves a detailed review on what might need
79
-
addressing
139
+
addressing
80
140
* A discussion breaks out on the best way to resolve an encountered problem
81
-
with the PR, each of these comments is a contribution
141
+
with the PR, each of these comments is a contribution
82
142
* And, of course, the PR itself is a contribution.
83
143
84
144
If the PR passes Review then it'll be marked as Approved and merged into the
85
-
codebase, that will trigger the associated Issue to close as complete and now
86
-
the Error Fix or Functionality in question will be fully implemented into
87
-
the project.
145
+
codebase, that will trigger the associated Issue to close as complete and now
146
+
the Error Fix or Functionality in question will be fully implemented into the
147
+
project.
88
148
89
149
To get here it took multiple contributions, from different community members,
0 commit comments