Problem/Motivation

Github recently added new community tools which lints projects for their own open-source community recommendations, one of which is that "a CONTRIBUTING file tells your audience how to participate in your project.".

Proposed resolution

Add a core/CONTRIBUTING.txt to Drupal's repository, with the contents of Drupal's Ways to get involved documentation.

I suggest putting it in whichever folder holds MAINTAINERS.txt (i.e.: another piece of documentation you'd probably want to read if you wanted to interact with the Drupal community). In Drupal 8, MAINTAINERS.txt is in the core sub-directory; in Drupal 7 MAINTAINERS.txt is in the root folder.

I suggest we make it a .txt (as opposed to a markdown document / .md) to be consistent with other documentation in that directory.

I suggest we use the text from https://www.drupal.org/contribute because:

  1. that's a pretty comprehensive jumping-off point regardless of the reader's specialty (i.e.: it's for more than just developers),
  2. the text on that page doesn't change as often as the pages it links to (i.e.: less work to keep the file in-sync with the page on d.o), and,
  3. we have a lot of documentation on contributing, arguably more than we can reasonably expect someone to read in a single file.

Remaining tasks

  1. Write a patch
  2. Review and feedback
  3. RTBC and feedback
  4. Commit
  5. Discuss how to backport to 7.x

User interface changes

None.

API changes

None.

Data model changes

None.

CommentFileSizeAuthor
#37 comparison.png126.1 KBbrahmjeet789
#34 Add-Contributing-txt-2886296-34.patch4.66 KBkanav_7
#33 Contributing-txt-2886296-33.patch4.67 KBmohit1604
#31 Add-Contributing-txt-2886296-31.patch4.69 KBkanav_7
#20 contributingtxt-2886296-20.patch4.67 KBdani3lr0se
#14 contributing-txt-2886296-14.patch4.67 KBdani3lr0se
#13 contributing-txt-2886296-#10.patch4.67 KBdani3lr0se
#10 contributing-txt-2886296-10.patch4.67 KBdani3lr0se
#2 2886296-2-add-contributing-txt.patch4.5 KBmparker17
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

mparker17 created an issue. See original summary.

mparker17’s picture

mparker17
he/him
Primary language English
Location UTC-4
CreditAttribution: mparker17 as a volunteer commented
Assigned: mparker17 » Unassigned
Issue summary: View changes
Status: Active » Needs review
FileSize
2886296-2-add-contributing-txt.patch4.5 KB

Here's a patch for the 8.4.x branch. Reviews welcome!

mparker17’s picture

mparker17
he/him
Primary language English
Location UTC-4
CreditAttribution: mparker17 as a volunteer commented
Issue tags: +Novice

(tagging as a novice issue)

mparker17’s picture

mparker17
he/him
Primary language English
Location UTC-4
CreditAttribution: mparker17 as a volunteer commented
Issue summary: View changes

(formatting changes to the issue summary)

naveenvalecha’s picture

naveenvalecha
He/Him
Primary language Hindi
CreditAttribution: naveenvalecha as a volunteer commented 
+++ b/core/CONTRIBUTING.txt
@@ -0,0 +1,109 @@
+  https://www.drupal.org/docs/7/theming/howto/customizing-core-andor-contributed-themes

Do we have the documentation page for Drupal 8?

mparker17’s picture

mparker17
he/him
Primary language English
Location UTC-4
CreditAttribution: mparker17 as a volunteer commented

@naveenvalecha, the link was copied directly from https://www.drupal.org/contribute : I'm tempted to say that's a discussion for the maintainers of that documentation page. For reference, the D8 theming guide is at https://www.drupal.org/docs/8/theming

dawehner’s picture

dawehner
Primary language German
CreditAttribution: dawehner as a volunteer commented

just some drive by review 

  1. +++ b/core/CONTRIBUTING.txt
@@ -0,0 +1,109 @@
+- Mailing lists: https://www.drupal.org/mailing-lists

    I think we should point to IRC/Slack instead 

  2. +++ b/core/CONTRIBUTING.txt
@@ -0,0 +1,109 @@
+- Issue tracker: https://www.drupal.org/project/issues

    This points to all issues instead of the core specific ones

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford at OpenConcept Consulting Inc. commented

I like this idea. Neat suggestion by Github. Thanks for getting this started Matt!

I'd suggest:

- Adding a section for accessibility.
- Adding something about social media. "Thank those users or the projects that make your work a success"
- Could also ask folks to blog about it and add links back to the projects they use

@naveenvalecha good point. Maybe best to point to https://www.drupal.org/docs/8 for now. Though really not sure that the D8 docs have a
Theming HowTo that is updated.

@dawehner 1. agreed. Who uses Mailing lists? 2. I'd agree that it should focus on the core specific issues. I do think though that core does have a responsibility to point people to broader Drupal issues.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented
FileSize
contributing-txt-2886296-10.patch4.67 KB

Hi all. I created a new patch that addresses the feedback in #5, #7 and #8. I made a new patch, rather an interdiff because I made it for 8.5.x. I hope this was ok. I'd be happy to do it another way if necessary. Thanks for your time and help. :)

Status: Needs review » Needs work

The last submitted patch, 10: contributing-txt-2886296-10.patch, failed testing. View results

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented

Hmmm. Something is weird. It's showing that I deleted the file instead of adding it. I'll fix it. My apologies. :(

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented
FileSize
contributing-txt-2886296-#10.patch4.67 KB

Here is the patch showing that I actually added the file. Sorry all. :(

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented
FileSize
contributing-txt-2886296-14.patch4.67 KB

Third time is the charm, right? I'm very sorry. :(

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented
Status: Needs work » Needs review

The last submitted patch, 13: contributing-txt-2886296-#10.patch, failed testing. View results

volkswagenchick’s picture

volkswagenchick
she/her
Primary language English
Location San Francisco Bay Area
CreditAttribution: volkswagenchick at Hook 42 commented

I tested the patch using Simplytest.me and the patch applied smooth. Since it is documentation, there was no UI testing.
I reviewed the patch for grammar and spelling, tested all links, and reviewed formatting.

One minor nitpick:

+++ b/core/CONTRIBUTING.txt
@@ -0,0 +1,126 @@
+savvy to work in promoting Drupal and spreading the word! You can also share work

Line breaks should be at 80 characters as per Drupal documentation standards

volkswagenchick’s picture

volkswagenchick
she/her
Primary language English
Location San Francisco Bay Area
CreditAttribution: volkswagenchick at Hook 42 commented
Status: Needs review » Needs work

Marking as needs work.

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented
Assigned: Unassigned » dani3lr0se

I will work on this later today and update. Thanks for reviewing. :)

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented
Assigned: dani3lr0se » Unassigned
Status: Needs work » Needs review
FileSize
contributingtxt-2886296-20.patch4.67 KB

Here is a new patch that addresses the line wrapping at 80 characters. I made an interdiff, but it didn't recognize the difference in line wrapping. So here is the new patch with line wrapping at 80 characters. It was already set to 80 characters, but the difference was that my editor was set to automatically wrap at 80 characters rather than just manually wrapping at 80. Setting to manual wrapping at 80 is what fixed this.

volkswagenchick’s picture

volkswagenchick
she/her
Primary language English
Location San Francisco Bay Area
CreditAttribution: volkswagenchick at Hook 42 commented
Status: Needs review » Reviewed & tested by the community

I used simplytest.me to test the patch and it applies. The nitpick is comment #17 was addressed.

Grammar, formatting, and readability are good.

The issues in comments #5 and #7 were addressed were appropriate links.
An accessibility section was added to address comment #8.

Since this is documentation there are no UI issues to test. Marking as RTBC.

Thanks for all the work on the issue.

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
CreditAttribution: larowlan at PreviousNext commented
Priority: Minor » Normal
Issue tags: +Needs release manager review, +Needs product manager review

Tagging for reviews

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
CreditAttribution: larowlan at PreviousNext commented

My 2c: I would prefer we just link to the docs on drupal.org for the following reasons:

- these things have a tendency to get out of date
- requiring a patch to update it is arduous
- anyone can update docs pages

But let's see what others think first

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented

@larowlan, that makes sense. I actually like that idea better. :)

xjm’s picture

xjm
she/her
Primary language English
CreditAttribution: xjm as a volunteer commented

FWIW I agree with #23. What's in this patch is great! But let's put this work into the handbook and then just have the file link the handbook page so that it can stay current.

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented

Sounds good. Thanks for the feedback @xjm. What is the process for putting this into the handbook? Or is that something that I could do? Thanks so much for your feedback and help. :)

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
CreditAttribution: larowlan at PreviousNext commented
Issue tags: -Needs release manager review

Let's wait for a final review from a product manager, @xjm has given it the release manager once-over.

In terms of getting it in the handbook, if you can edit the page, all good.

If not, it would need an issue filed in the documentation queue

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 20: contributingtxt-2886296-20.patch, failed testing. View results

Ivan Berezhnov’s picture

Ivan Berezhnov CreditAttribution: Ivan Berezhnov as a volunteer and at Drupal Ukraine Community for Levi9 commented
Issue tags: +CSKyiv18

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

kanav_7’s picture

kanav_7 CreditAttribution: kanav_7 at Google Summer of Code commented
FileSize
Add-Contributing-txt-2886296-31.patch4.69 KB

Updated in drupal 8.6.x

volkswagenchick’s picture

volkswagenchick
she/her
Primary language English
Location San Francisco Bay Area
CreditAttribution: volkswagenchick at Hook 42 commented

Looks good, One minor fix needed, leaving status as need works.

+++ b/core/CONTRIBUTING.txt
@@ -0,0 +1,126 @@
\ No newline at end of file

Should have a blank line at the end of the file

mohit1604’s picture

mohit1604 CreditAttribution: mohit1604 at Google Summer of Code commented
Status: Needs work » Needs review
FileSize
Contributing-txt-2886296-33.patch4.67 KB

This should be fine.

kanav_7’s picture

kanav_7 CreditAttribution: kanav_7 at Google Summer of Code commented
Status: Needs review » Needs work
FileSize
Add-Contributing-txt-2886296-34.patch4.66 KB

@volkswagenchick : Fixed that. Please Check Now.

dani3lr0se’s picture

dani3lr0se CreditAttribution: dani3lr0se at Hook 42 commented
Status: Needs work » Needs review

Assigning as Needs Review per #34.

cilefen’s picture

cilefen CreditAttribution: cilefen at Institute for Advanced Study commented
Related issues: +#2940739: Project messaging channel in core initiative

I love this issue. That said this would be more maintainable as a brief message followed by one hyperlink to the contribution guide. We have as much documentation in git to deal with as we can already.

brahmjeet789’s picture

brahmjeet789 CreditAttribution: brahmjeet789 as a volunteer and at gai Technologies Pvt Ltd commented
FileSize
comparison.png126.1 KB

@mohit1604 and @kanav_7 i have viewed your patch but i am unable to see any diifernece in both patches i am attaching screenshot of diif please check

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

jibran’s picture

jibran
he/him
Primary language Urdu
Location Sydney, Australia
CreditAttribution: jibran as a volunteer and commented

Do we need a section on security here?

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

smustgrave’s picture

smustgrave CreditAttribution: smustgrave at Mobomo commented
Status: Needs review » Needs work
Issue tags: +Needs issue summary update, +Needs Review Queue Initiative

Brought this up on the #needs-review-queue-initiative with @quietone

Needs an IS update and a patch that reflects #23, #25. We need to decide where the page would be in the handbook, too

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.