1 of 68

First Time Contributors Workshop

DrupalCon North America

2 of 68

Let’s collaborate on Slack:

drupal.org/slack

#first-contribution

3 of 68

First Time Contributors Workshop

Chris Darke & other Mentors

slack: Chris Darke

d.o.: ChrisDarke

languages: English / Spanish

Link to slide deck:

bit.ly/dcon24pdx

4 of 68

Find a table / join a team
Find something to work on (an issue, etc)
If an issue, update issue
Decide what everyone will do
Keep issue updated
After event is over, keep contributing!

Dynamics of the Mentored Contribution

5 of 68

Why contribute
Benefits of contributing
Types of Contributions
Initiatives
Issue queue 101 / etiquette
Merge Requests
Tooling and documentation

Agenda

6 of 68

New to the world of Drupal
“I’ve been around forever but never done any contrib”
Looking for new ways to help out
Have not worked with the new process
Basically anyone!

Who are you?

7 of 68

If you depend on open source, open source depends on you
Your contributions are valued
Contributing makes you a more integrated part of the Drupal community

Why contribute?

8 of 68

Drupal depends on sharing
Good corporate citizenship
Talent recruitment
People love the community and attending events

Why agencies should contribute?

9 of 68

Create an account to contribute

https://www.drupal.org/user/register

10 of 68

Drupal.org profile

Name/User name
Work
Profile pic
Social Links
Mentors

11 of 68

You can still contribute without coding

You can be a huge asset to the project without

ever writing any code

12 of 68

Improve documentation
Issue triage
Translations
Review content
Marketing
Event organization
Sharing knowledge / Mentor

Types of contributions

Community

13 of 68

Test experimental features
Creating merge request (code)
Test existing Merge Requests on issues (eg. with DrupalPod)
Provide feedback

Types of contributions, cont.

Code

14 of 68

Documentation�drupal.org/documentation

15 of 68

Official

Official guides are governed by maintainers and held to an established standard through an editorial process.

Drupal Documentation Guides

16 of 68

Changes via Issue Queue as changes to asciidoc files.

Editing Curated Guides

17 of 68

Community

Community documentation can be freely edited by any member of the Drupal community. It is not subject to any formal editorial process.

Drupal Documentation Guides

18 of 68

Changes via edits to the page itself as revisions, with justification for changes provided.

Editing Community Documentation

19 of 68

Contributor

Various guides and guidelines on using Drupal.org tools and services.

Drupal Documentation Guides

20 of 68

Contrib

Documentation for contributed modules for Drupal 8 and later versions.

Drupal Documentation Guides

21 of 68

Drupal.org documentation

Various guides and guidelines on using Drupal.org tools and services.

User accounts
Content guidelines
Marketplace guidelines
Moderation and maintenance
GitLab Integration
etc

22 of 68

Translations / i18n�localize.drupal.org

23 of 68

Join a Team
Read up on documentation

Roles:

Translate user interface text
Review a translation
Translator
Translation moderator

Translations / i18n

24 of 68

drupal.org/association

25 of 68

Marketing�/community/promote-drupal

26 of 68

Drupal Ambassadors

Promote Drupal in your networks:

Sharing articles on social media
Resharing other’s articles
Talking about Drupal at tech events outside of Drupal

27 of 68

Promote Drupal

Presentations
Social Media
Photography
Logos

28 of 68

Marketing Role and Tasks

Project lead
Writer
Designer
Videographer
Communicator or other marketing role
Drupal Recording Initiative

29 of 68

Drupal Recording Initiative

Training and mentorship
Expanded coverage
Improved documentation
Higher recording success rate
Streamlined funding
Overall organization
Content discoverability

30 of 68

Issue Queue

Contributing Back to

Code

31 of 68

Core vs. Contrib

32 of 68

Extending Drupal

Distributions
Themes
Recipes
Modules

Drupal.org is where most code that makes Drupal sites work including the core Drupal project. All Drupal websites run a version of core. What makes each website different are the additional contributed modules that are added. That is often referred to as Contrib.

You can pick and choose from a wide range of contributed modules to add functionality to your site, and from a wide range of contributed themes to change your site's appearance. These add-on modules and themes are also known as “contrib” because they were contributed by members of our Drupal community, and are available on Drupal.org free of charge.

Distributions provide site features and functions for a specific type of site as a single download containing the core software, contributed modules, themes, and pre-defined configuration.

A theme is a set of files that define the visual look and feel of your site.

What is a module?

A module is a set of PHP, JavaScript, and/or CSS files that extends site features and adds functionality

33 of 68

Start small and work your way up

Report an issue
Update issues
Triage issues
Create Merge Requests
Provide feedback
Testing

34 of 68

Issue Queue 101

35 of 68

Drupal Core Issue Queue

drupal.org/project/issues/drupal

36 of 68

Drupal Core Issue Queue

bit.ly/drupal-novice

37 of 68

The Drupal Issue Queue

38 of 68

The Issue Queue - Advanced Search

39 of 68

The Issue Queue - Advanced Search

40 of 68

Issues for novices to steer clear of...

Projects not actively maintained
Multiple issues marked “won’t fix”
Issues that are not current
Issues with over 20 comments
Issues that have changed status many times / a lot of discussion
Critical vs Normal vs Minor

41 of 68

Merge Requests

As of November 2020, we have a new workflow available, similar to what open-source contributors commonly use on sites like GitLab.

42 of 68

Anatomy of an Issue

43 of 68

Necessary Metadata

Title
Category
Priority
Status
Version

Component
Tags
Assigned
Summary

Title - A descriptive heading for the issue.

The issue title is displayed in issue lists, so make sure it is both descriptive and short.

Category this is where indicate if this is a task, a bug report,feature request, road map, support and so on…this is a drop down

Priority - The relative importance of an issue in relation to the project and other issues

Status - The current state in the life-cycle stages of the issue, and if it is resolved, the type of resolution.

Version - Normally, set this to the current development version of the project, rather than the exact release version where you noticed the problem.

Component - The part of the project that the issue falls in. This can change based on the project - especially non code projects like camps

Tags - A non-hierarchical keyword or term to further categorize the issue. Autocomplete is our friend…

Assigned- DO NOT ASSIGN YOURSELF CORE ISSUES The username of the person who is working on the issue.

Unassigned: The issue has no one assigned to it. This is the typical setting for issues and is the default.

Summary

Description of the issue. Following the issue summary template is recommended, if this is an issue for a software project; for a non-software project, most of the template still applies.

44 of 68

Necessary Metadata

45 of 68

Summary template:

Problem/motivation
Steps to reproduce
Proposed resolution
Remaining tasks
UI and API changes
Data model changes

Issue Summary

The issue queue now provides a summary template:

Problem/Motivation

(Why the issue was filed, steps to reproduce the problem, etc.)

Steps to reproduce

(Detailed instructions on how to reproduce the issue, including exact versions used, specific paths to visit, what actions to take, etc.)

Proposed resolution

(Description of the proposed solution, the rationale behind it, and workarounds for people who cannot use the patch.)

Remaining tasks - (reviews needed, tests to be written or run, documentation to be written, etc.)

UI - (New or changed features/functionality in the user interface, modules added or removed, changes to URL paths, changes to user interface text.)

API changes - (API changes/additions that would affect module, install profile, and theme developers, including examples of before/after code if appropriate.)

Data model changes - (Database or configuration data changes that would make stored data on an existing site incompatible with the site's updated codebase, including changes to hook_schema(), configuration schema or keys, or the expected format of stored data, etc.)

Details to include

Why are we doing this? Above all, a summary should explain why a change is needed, in a few short sentences.

For majors and criticals: Why is the issue major or critical? For criticals, how does it block release?

For bugs: Steps to reproduce the issue on a fresh installation of HEAD.

For blockers: What issues is this blocking, and why?

If you are reporting an issue in the Documentation project, the User Guide project, or another working group that deals with documentation, make sure to include the URL of the page you are discussing in your issue summary.

46 of 68

Issue summary templates used in special situations:

Special issue summary templates

47 of 68

You should be able to understand the issue and its current status
Summary should use short, clear sentences
It should use markup for better readability
It should Identify the key points
Include links to particular comments
The UI and API changes sections can be left as "TBD"

Issue Summary - General guidelines

You should be able to understand the issue and its current status

Summary should use short, clear sentences

It should use markup for better readability

It should Identify the key points

Include links to particular comments

The UI and API changes sections can be left as "TBD"

Details to include

Why are we doing this? Above all, a summary should explain why a change is needed, in a few short sentences.

For majors and criticals: Why is the issue major or critical? For criticals, how does it block release?

For bugs: Steps to reproduce the issue on a fresh installation of HEAD.

For blockers: What issues is this blocking, and why?

If you are reporting an issue in the Documentation project, the User Guide project, or another working group that deals with documentation, make sure to include the URL of the page you are discussing in your issue summary.

48 of 68

Issue Queue Transparency

49 of 68

Issue Queue Transparency

When to be transparent:

If it's your first time doing something
Why you’re using a specific tag
If the issue is being held for new contributors
Who is helping with the issue
Why you’re assigning yourself

50 of 68

Issue Queue Etiquette

51 of 68

Things to do

Report the issue in the correct project.
Read any relevant documentation.
Investigate if the issue already been fixed in the latest version.
Try to get help from the community

Issue Queue Etiquette

52 of 68

Things to do

Search the Issue Queue for the same or similar issues
Provide as full of a description of the problem as possible
Come back and report if a solution worked for you or not

Issue Queue Etiquette

Do: If you find a similar issue, consider whether your issue is really the same or you should create a new issue. If the issue is "Closed", very few people will see your post, and some project maintainers may delete such posts as noise. Always check the status and avoid posting in closed issues. If the issue is open and you have more details that could help get the bug resolved or understood, add them. Confirming that an old bug is still relevant (if it's still open) is also helpful.

Do: Provide as full of a description of the problem as possible, using the issue summary template. More details help developers to more easily track down the problem. For example, what version of Drupal are you running? What version of PHP are you running? What actions did you perform to see the bug? What did you expect to happen, and what happened instead? If the error came about as a result of some code you wrote, paste the code snippet.

Do: Come back and tell the community if a particular solution worked for you or not. If you post a question and then find an answer elsewhere come back and post a link to it. You will help people who come after you and you'll be surprised how many people will notice that you're helpful and you are more likely to get better help yourself in the future.

53 of 68

Things to do

When tagging utilize the autocomplete functionality.
Follow the guidelines for when to assign an issue to yourself.
Remember to leave novice issues for new contributors.

Issue Queue Etiquette

54 of 68

Things to AVOID

Don't: Report a security problem in a regular Drupal issue
Don't: "Hijack" other issues
Don't: Mark an issue RTBC without testing
Don’t: Don’t just change a .txt file to a .md file

Issue Queue Etiquette

55 of 68

Things to AVOID

Don't: Change the status of an issue from "Fixed" to "Closed (fixed)"
Don’t: Open an MR or upload a patch on a fixed/closed issue
Don't: Create an empty fork

Issue Queue Etiquette

56 of 68

Use of AI

57 of 68

Development Tools�drupal.org/tools

58 of 68

Development Tools

DrupalPod (what we will be using)
Local development environment

DDEV, Lando, Docksal,

Tugboat
SimplyTest.me

59 of 68

DrupalPod

Download the DrupalPod browser extension - Chrome or Firefox
Go to any issue page on Drupal.org (core, module, or theme)
Select the DrupalPod extension
(Optional) Choose a patch / issue fork / branch

Note: You will need a github account

60 of 68

DrupalPod Walkthrough

61 of 68

Create issue fork - Creates whole new fork of project
Create a branch on fork - [Issue#]-[Short-Description]
Make changes and commit with meaningful message
Open Merge Request
If everything passes, branch in fork is merged into project

Forking and Merge Requests

62 of 68

Merge Request Walkthrough

63 of 68

Drupal Strategic Initiatives�/about/core/strategic-initiatives

64 of 68

Drupal Community Initiatives�/community-initiatives

65 of 68

Contribution Videos�bit.ly/drupal-contribute

66 of 68

Video playlist

67 of 68

Resources

68 of 68

That’s all folks!

Slideshow available at https://bit.ly/dcon24pdx