|
| 1 | +title: Considering Community Contributions at Creative Commons |
| 2 | +--- |
| 3 | +categories: |
| 4 | +open-source |
| 5 | +collaboration |
| 6 | +community |
| 7 | +--- |
| 8 | +author: sara |
| 9 | +--- |
| 10 | +pub_date: 2023-03-24 |
| 11 | +--- |
| 12 | +body: |
| 13 | + |
| 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. |
| 86 | + |
| 87 | +If this happens, the Issue will be moved to a status of "discarded", and will |
| 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. |
| 92 | + |
| 93 | +Sometimes an Issue might describe something much broader than can be easily |
| 94 | +contained within itself and may be converted to a status of "discussion". This |
| 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 |
| 103 | +status of "blocked". They'll sit in that state until they're unblocked and the |
| 104 | +work can happen. |
| 105 | + |
| 106 | +If an Issue seems like it doesn't have enough information to determine what to |
| 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. |
| 109 | + |
| 110 | +Remember, an Issue is a form of documentation, and in a way it's a |
| 111 | +conversation, and that means that until it moves forward it's very much a work |
| 112 | +in progress. |
| 113 | + |
| 114 | +If an Issue passes through this period as implementable, then it'll move to a |
| 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) |
| 119 | + |
| 120 | +During this process it is worth noting that there will be multiple types of |
| 121 | +contribution. For example: |
| 122 | + |
| 123 | +* The Issue itself is a contribution |
| 124 | +* Comments on the Issue from the community refining it are each contributions |
| 125 | +* Someone's comment on the Issue helping another person sort out why the Error |
| 126 | + is occurring is a contribution. |
| 127 | +* Someone finding another related Issue and linking it as relevant to that |
| 128 | + Issue is a contribution. |
| 129 | + |
| 130 | +All of these contributions occurred before a Pull Request was ever initiated. |
| 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: |
| 135 | + |
| 136 | +* The code work encounters a problem, someone asks for assistance within their |
| 137 | + draft PR, and several members offer help as comments. |
| 138 | +* Someone reviews the final PR and leaves a detailed review on what might need |
| 139 | + addressing |
| 140 | +* A discussion breaks out on the best way to resolve an encountered problem |
| 141 | + with the PR, each of these comments is a contribution |
| 142 | +* And, of course, the PR itself is a contribution. |
| 143 | + |
| 144 | +If the PR passes Review then it'll be marked as Approved and merged into the |
| 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. |
| 148 | + |
| 149 | +To get here it took multiple contributions, from different community members, |
| 150 | +that's the power of open source! |
0 commit comments