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!

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.

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.

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.

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.

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.

Whether an Error or Feature/functionality Issue, once it's been submitted, in

accordance with the Contribution

Guidelines, 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.

If this happens, the Issue will be moved to a status of "discarded", and will

be closed with a comment explaining why. The other reason an Issue might be

moved to "discarded" is that it duplicates the work in another Issue, which is

why it's important to first check all the existing Issues prior to submitting a

new one.

Sometimes an Issue might describe something much broader than can be easily

contained within itself and may be converted to a status of "discussion". This

means that the Issue should spark a larger conversation within the community to

consider all the angles of abstract, and possibly split the idea up into more

manageable pieces across multiple Issues. Other outcomes might be a discussion

that realizes that while the idea is sound, it's not implementable at this time

and won't move forward.

Some Issues are solid ideas, but they are not something that can move forward

until work on other Issues is completed first. As such they tend to move to a

status of "blocked". They'll sit in that state until they're unblocked and the

work can happen.

If an Issue seems like it doesn't have enough information to determine what to

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.

Remember, an Issue is a form of documentation, and in a way it's a

conversation, and that means that until it moves forward it's very much a work

in progress.

If an Issue passes through this period as implementable, then it'll move to a

status of "ready for work". This is the point at which it can be implemented,

and a contributor can submit a Pull Request addressing it. (See the Repository

Labels Status section for more

information)

During this process it is worth noting that there will be multiple types of

contribution. For example:

The Issue itself is a contribution

Comments on the Issue from the community refining it are each contributions

Someone's comment on the Issue helping another person sort out why the Error

is occurring is a contribution.

Someone finding another related Issue and linking it as relevant to that

Issue is a contribution.

All of these contributions occurred before a Pull Request was ever initiated.

Once an Issue enters a status of "ready for work" someone who has indicated

interest on that Issue will be assigned to it and can then fork the repository,

make a branch to work within, and once settled submit a Pull Request. That

process alone may involve several contributions as well, such as:

The code work encounters a problem, someone asks for assistance within their

draft PR, and several members offer help as comments.

Someone reviews the final PR and leaves a detailed review on what might need

addressing

A discussion breaks out on the best way to resolve an encountered problem

with the PR, each of these comments is a contribution

And, of course, the PR itself is a contribution.

If the PR passes Review then it'll be marked as Approved and merged into the

codebase, that will trigger the associated Issue to close as complete and now

the Error Fix or Functionality in question will be fully implemented into the

project.

To get here it took multiple contributions, from different community members,

that's the power of open source!