Blogs

EMAIL: info@example.com

Drupal Association blog: A Drupal Contribution Guide – Guest Post

We have been sent the following rather fabulous guest blog post by Yogendra Prasad, Surabhi Gokte, and Karthik Kumar and we wanted to share it with everyone here. We would love to see this inside the upcoming Contributor Guide (more details of which coming soon…)


What is the Drupal Community?

The Drupal Community consists of all the members using Drupal and coming together to form a group and voluntarily give their time to contribute towards bettering the community.

Why should I contribute to the Drupal Community?

Come for the software, stay for the community!

Drupal has been our bread and butter for so many years and so it’s one of our prime duties to give back to the Drupal Community in whichever ways we can.

LEARN & GROW WITH THE COMMUNITY:

  • You get to learn as you work with the community worldwide
  • You get to present yourself which in turn brings visibility to both you and your organization
  • You get to know about the Drupal events happening throughout the community.
  • You get to participate in the events by speaking or volunteering.

Prerequisites:

  • Basic understanding about Drupal
  • Have done local setup earlier
  • Know how to Install Contributed Modules
  • Must have basic knowledge of Git
  • Must know how to Create/Apply Patch

What is the Life Cycle of a Drupal Issue?

Following can be the different states of an issue:

  • Active – When a new issue is created, it is in an Active state.
  • Needs work – When the issue needs to be worked upon, it is in a Needs Work state.

One can pick the issues from either of the two states to start with.

  • Needs review – Once the issue is picked, the patches are successfully submitted and all the test cases are passing, the issue’s state should be changed to Needs Review.
  • Reviewed & tested by the community – Once the issue is reviewed by any contributor, the issue is moved to “Reviewed & tested by the community” (RTBC) state where one of the members from the core community team reviews the issue
  • Fixed – When an issue passes from the RTBC state, it is moved to the Fixed state
  • Closed (fixed) – After the Fixed state, the issue moves to Closed (fixed) automatically within two weeks. This is the last state of an issue.
  • Closed (duplicate) – When any issue gets created which is a duplicate of any earlier one, it directly gets closed as Closed (duplicate)
  • Closed (won’t fix) – This state represents that an issue has no solution
  • Closed (works as designed) – This state represents that an issue raised is providing the functionality what it was supposed to and so moved to “works as designed”. In other words, the issue raised is not a bug but a feature.
  • Closed (cannot reproduce) – When an issue is not reproducible is moved to this state.
  • Closed (outdated) – When an issue is either too old to fix or gets fixed within some other module’s issue, the state can be Closed (outdated) for that issue.

Other States:

  • Patch (to be ported): When a Patch is to be ported for other versions of Drupal/Contributed module.
  • Postponed: When the Issues/Feature/bug is postponed by the author/community, and doesn’t need a fix.
  • Postponed (maintainer needs more info): When an issue is raised but according to the maintainer of the Contributed module, more info is needed about the issue to get it fixed.

What ways can I contribute to the Drupal Community?

There are multiple ways to contribute to the Drupal community, and you don’t need to have a developer background to give something to the community.

  • Drupal Core issues: You can select issues from Drupal core from : https://www.drupal.org/project/issues/search/drupal to contribute. Here you can commit patches to the issue, review tickets that are in “needs review” and if you have found any issue in Drupal you can log here by providing basic details about the same.
  • Contribute a Module to Drupal: If you have any feature in mind that you think can be used in Drupal as a standalone module , so that a larger audience can start using it , you can add your module to Drupal. For creating and getting it approved you have to follow steps mentions here: https://www.drupal.org/developing/modules
  • Contributed Module Issues: Along with DrupalCore issues , there is a huge list of bugs/issues which you can pick for fixing by providing patches from contributed modules: https://www.drupal.org/project/issues/search.
  • Documentation: if you do not have any Development background or are not interested in contributing by writing code, another interesting way is to help Drupal.org in improving Documentation. Documentation in Drupal is needed in the form of README.txt in every single module/theme , in form of code commenting , class usage etc.
  • Validating Issues: If you are good at reviewing tickets or have QA background you start contributing to the Drupal community by verifying the fixes provided by any community member on the. For this you have to pick up tickets specifically which are in “needs review” status. List of issues you can found here: https://www.drupal.org/project/issues/search/drupal?text=&assigned=&submitted=&project_issue_followers=&status%5B%5D=8&issue_tags_op=%3D&issue_tags= , This list contains both Drupal core and Contributed modules issues , it’s up to you which you want to pick and start working.
  • Contribute financially: The Drupal Association is a nonprofit (501c3) organization serving the international Drupal community. One can also contribute to the Drupal Community in monetary terms by opting for the individual membership. Read more here – https://www.drupal.org/association/individual-membership.

Note: https://www.youtube.com/watch?v=INpedSOpdqw&feature=youtu.be

  • Log new Issue: You can also log your own issues to Drupal.org. The issue can be from both Drupal Core and Contributed modules. If you faced any issue while using Drupal in Core or any module you can go and log the issue directly to Drupal.org. Make sure to not log a duplicate issue.

How to start contributing?

How to get registered with Drupal.org?

The very first step is to register yourself on the drupal.org website by creating an account. Go to https://register.drupal.org/user/register. If you already have an account, simply login at https://www.drupal.org/user.

How to get registered to Drupal slack?

There are various communication channels to connect with the community, the famous one is Slack!

If you do not have an account on Drupal slack, go to http://drupalslack.herokuapp.com. Once there, you can join various channels as per your requirements like – #support, #frontend, #d9readiness etc. You can also search for channels by clicking on “+” > “Browse Channels” in the Channels section.

There are other mediums too like Telegram, Rocket Chat, IRC, etc. where people connect.

How to find issues?

Go to Drupal’s issue queue and filter the list based on your area of interest:

You can visit Drupal.org to find the issues you want to work on, for this please login to Drupal.org so that you can use the Advanced filter feature which only appears for logged in users.

For Drupal Core specific tickets : https://www.drupal.org/project/issues

For Combined list of Core and contributed modules issues list: https://www.drupal.org/project/issues

Basic guideline to find issues:

There are few filter criteria we follow before picking up any ticket from the issue queue, so these criteria helps us to get to ticket/issue closer faster. Following are the criteria:

The filters on issue queue will look like this:

  • Use issue tags: Novice, documentation, Drupal 9 compatibility : IF you are new to Drupal contribution arena , and you want to start with easy and straightforward issues that will help you boosting your confidence , then you can filter the issue queue with “ Novice, documentation, Drupal 9 compatibility” issue tags. This will give you the list of issues which are tagged with following tags only.
  • Use the Component filter of your interest : You can make use of this filter to get a list of issues of your interest area. For ex: Bootstrap system, Ajax System ets.
  • Use Status filter : Active/Needs Work/Needs review/Patch to be ported : By Default Issue list contains closed issues associated with irrelevant status, so to reduce the list of the issue use the mentioned status.
  • Sort issues list on ASC order of replies : This Sorting will give you the list of issues which have less number of replies, means no one has picked or less people have worked on the issue.
  • Sort Issues list on DESC order of Last updated: This will give you list of most active issues on which you can start working , Ideally we not prefer to pick issues which have last activity more than a Year ago, as it implies the issue is less active and there are huge chances that the issue will take more time to get closed in comparison with issue will more active.
  • Pick issues with empty “Assigned to” value: Please Keep in mind that it is not advisable to pick any ticket on which someone is already working or the ticket is already assigned to someone.

Note: You can use this URL to get directly to the filtered issue queue.

What to do after finding the issue?

As you identified the issue on which you want to work/contribute you can follow the following steps to help the issue to get more close to its closure state.

Note : Keep in mind about the version of Drupal Core/ contributed Module for which the issue has been raised by the author. You can get the version on the issue detail page as shown in image.

In the Given Image the Issue project is Drupal Core and the version for which the issue is reported is 8.8.x-dev.

How to Setup a Local machine to replicate the issue?

Now you have to be ready with your local setup of the machine. Local setup is necessary in case you want to give a patch to the issue or even if you want to test a patch on a given issue.

As per mentioned above, you have to set up an exact version of Drupal Core/ Module on your machine for which the issue has been reported.

  • If the issue belongs to Drupal core and you need to set up a specific version of Drupal core you have to follow : https://www.drupal.org/project/drupal/git-instructions to setup Drupal.
  • If the Issue belongs to the Contributed module , in this case setup Drupal with the latest stable version available on your machine and then clone the module which is needed to replicate the issue. For ex in the given image below you can see the module version for which the issue has been reported.

Now you have to get this specific version on your machine to replicate the issue and to fix, for this visit the detail page of the module as given in the above image , and on the detail page you will have a link for version control. For example, have a look at the image below:

When you click on version control you will get page as given in the below image:

Now you have to follow the steps and clone from the specific branch for which the issue has been reported.

Note: Make sure you have Drupal Installation already and make sure to place/clone the module at the proper directory so that you can use the module and fix the issue.

  • Get understanding of issue: First step is to get complete understanding about the issue , try to replicate the issue on your local machine for the same version for which the issue has been reported.
    • In case of any query, put appropriate comments to the ticket and ask for more details..
      • Try to replicate the issue in your local environment.
      • Once you have a clear understanding of the issue and have an idea /approach to fix it , Assign issue to yourself so that other community members will not take it up.
      • Add necessary tags to issue: Usually in code sprints and Drupal events when we pick any issue we add a relevant tag to the ticket so that we get to filter the list of tickets from the tag and get a list of issues picked in that particular event.
      • Depending on the state of the ticket, start working on it.

How to Contribute by adding a patch to the issue?

  • Once you have started work on the ticket, you might be able to get the resolution or you might have some more questions.
  • Comment back in ticket, with the questions and follow up ticket.
  • If you are having resolutions, that would be a piece of code change / style fix / Adding Readme / Annotation changes etc.
  • There might be issues, which already have some patch, at that point you have to add changes to the existing patch and get the interdiff.
  • After the issue is fixed, test it locally and create a patch.
  • Try to execute the unit test on your local machine , to make sure that unit tests are working fine.
  • If you have to write any test cases for your changes, do the same.
  • Your patch attaching to ticket will be like either one of the below
    • Patch file + comments
    • Patch file + Interdiff file + comments

How to create a patch?

  • Use GIT command to create patch
  • In case of new patch
    $ git diff
    $ git diff > <ticket-number>-<comment-number>.patch
    

    • In case of an existing patch, download it.
      $ wget <patch-url-from-ticket-to-download>
      $ git apply -v <download-patch>
      

      Make the changes needed existing patch

      $ git diff
      $ git diff > <ticket-number>-<comment-number>.patch
      $ interdiff <old-patch> <new-patch> > interdiff_<old>-<new>.txt
      
      • Naming of patch
        • Patch name
          <ticket-number>-<comment-number>.patch
          
          • Interdiff name
            interdiff_<old-comment-number>-<newcomment-number>.txt
            
            • Validate patch on your machine
              $ git apply > <new>.patch
              
              

How to attach a patch to Issue?

  • Add patch as a file to issue with needed information in comment
  • Update ticket status to Needs Review after Applying patch and unassigned it
  • If patch turns green and passes all test cases issue is ready to be reviewed by community

    • If patch fails then look into the logs and try to rework on the issue by assigning back to yourself.
    • In case need help seek help from community via adding comment to ticket or on Drupal slack

How to Contribute by reviewing an issue?

There is a great opportunity for folks who do not want to contribute to Drupal by giving patches, instead you can start reviewing/ testing patches that are getting applied for corresponding issue

.

  • Get the issue list filter with “Needs Review”: To Review any patch provided for the issue you have to filter the issue queue using “Needs Review” for both Drupal Core issues and Contributed module issues.
  • Identify the issue on which you can do the testing/reviewing.
  • Make sure to pick the latest patch applied to the issue, As given in the image below:

As you can see there are lists of patches applied for this issue , but you have to work/review the latest patch applied to the issue ,which will be sorted by Comment ID in DESC order.

  • Make Sure the Patch has passed all the Unit test cases and have turned to green color , like in the given image.
  • If possible you can have a look at the patch for the code changes done to fix the issue. You can have a look to analyse the coding standards, indentations , logic or any technical debt.
  • If you have any comment/feedback/suggestions on the patch , just go ahead and add a relevant comment to the issue regarding the patch.

Reviewing Patch Using “Dreditor”:

There is a Browser plugin which you can use to test the patch on virtual/temporary setup using Simplytest.me, Setup this Plugin on your Browser. Make sure to restart your browser before using it.

Now when you visit to Issue detail page which you already shortlisted for reviewing , you will able to see image as below :

Two new action buttons will be displayed.

  • Testing/verifying patch using Simplytest.me: As you want to test the particular patch you have to now click on “Simplytest.me” button to initiate setup process.
  • After clicking you will be redirected to page as given in image:

  • Here you have to select the version for which you want to validate the patch, Version will be as same as mentioned on the issue.
  • After selecting the correct version , click on “Launch SandBox”. There will be a process to setup a environment will initiate, like in image given below:

This will take some time to complete.

  • Once the process is completed you will land on the Drupal site , which already have the patch applied to the code base.
  • Admin Login: If you want to login to the system you can use: admin/admin as username/password for the system.

Reviewing Patch on a Local machine:

It is always better to test/verify the patch locally instead of using simplytest.me. For this you have to follow the following steps.

  • Setup local environment: Once you are ok with the Code changes done in the patch you can start setting up your local machine for the corresponding version mentioned in the issue for Drupal Core/Contributed Module. Follow the steps given above to set up your local machine.
  • Apply Patch on Local Environment: Now you can download patch by clicking on the patch link directly to your local machine and then apply the patch on your machine using :
    git apply > <patch-file-downloaded>
    
    Note: Make Sure about the path on which you are while applying the patch.
    
    

Validating/Testing the Patch (Cloud/Local):

  • Testing: Test the patch locally and verify that the issue has been fixed after applying the patch. Try to test for regression as well.
  • Patch is working fine and the issue got Fixed: If you feel the patch is correct and working fine as per your expectation and as per the criteria mentioned in the issue , then update the status to “RTBC”(Reviewed and tested by community) from Needs Review. Add Needed comments/Images/Videos to support your points.
  • If you feel you need more eyes needed to help you then make a comment to the tickets about the steps you took for testing and ask for more people to look into it.
  • Seek help on Drupal slack in case needed.
  • Issue is not fixed/Bug still exists: If you see the bug/issue is still appearing and not fixed by the patch, then add your relevant comment by tagging the author of the patch in comment and move the ticket status back to “Needs Work”.

Next Steps after Contributing to Issue (Reviewed/Applied Patch):

Once you have done your job on the issue, do the following:

  • Put a proper comment on the ticket about your work. Add screenshots if necessary.
  • Move the ticket to the next relevant state i.e from “Needs Works” => “Needs Review” or from “Needs Review” => “RTBC”
  • Attribute your contribution by adding an organization and customer, if appropriate. Refer screenshot below:
     

Also, you should keep following points in mind to check for any updates on the issue:

  • An update to the issue can be a new comment , Information updated for the issue or state changes to the issue.
    • Keep monitoring your Dashboard: Drupal.org provides you a personal Dashboard, which contains your latest activities and issues list on which you recently contributed. You should keep a close eye on the Dashboard and see the progress on issues you worked on.

      You can access your dashboard after you logged in to the site and hover on your user image on the header section as displayed in image below:

  • You will be receiving all updates on the issues via mail on your Drupal.org mail ID
  • In case needed i.e if ticket status is moved back to Needs work/Needs Review and you feel you can work/contribute to it , Then you can pick the issue and work on iit accordingly.
  • If the status of the ticket is closed, no need to do anything now on this ticket.

When is a Credit received for the contribution?

NOTE: It’s not mandatory that you will always receive credit for a closed issue on which you worked.

Once the issue is marked Fixed, the maintainer chooses which contributors on the issue will receive credit. Usually these are the contributors who…

  • When you submit a successful patch for an Active or Needs Work issue
  • When you review any existing patch of a Needs Review issue
  • When you create a new issue