Establish policies for external bots or tools that post or modify content on drupal.org

I added some more separation to show where the guidelines end and where the application of the proposed guidelines to recent situations starts.

One part I disagree with, but that I didn't change is:

That user must provide their username and password to the tool, which must then log in to drupal.org with the provided credentials, so that all modifications are done under the name and permissions of the responsible user.

This seems overly prescriptive. How about just saying that the user must provide the ability for the bot/tool to log in as them. Whether that's done with username/password or a session cookie or oauth is up to the maker of the bot/tool.

I'm the maintainer of PA robot, who automatically reviews drupal.org project applications.

That robot posts a lot of comments and I would not want to run it under my user name, as it would pollute my track record, notifications etc. So that robot user account is in direct conflict with the policies proposed here, since it does not post on behalf of humans. Maybe we consider it on the same level as the test bot?

So while these policies might make sense for use cases such as the Github Sync robot, where content is posted on behalf of users, they might not make sense for robots in general.

FWIW, the Druplicon bot theoretically falls into this bucket, too. (It interacts with drupal.org pages and stores logs.)

Depending on how you interpret the text, the policy could even apply to Dreditor.

Use of the tool should not increase the fragmentation of content, e.g. by scattering information that should be consolidated in one place, or by placing important related content on external sites where it may be lost.

Not sure how this is related to the policy. Sounds off-topic to me.

Polluting/Duplicating information somewhere else may be necessary to make a new/experimental alpha/beta-quality service possible in the first place. We should not be afraid of that.

Instead, the necessity/existence should be interpreted as a constructive sign that we're lacking web service APIs. However, the apparent non-existence of such fragmentation is a testament to drupal.org's APIs and willingness of service/tool designers to work and collaborate on solutions that resolve issues for the community at glance.

In any case, I don't see how it's related here and I think that sentence should be removed.

2. That user must provide their username and password to the tool, which must then log in to drupal.org with the provided credentials, so that all modifications are done under the name and permissions of the responsible user.

I agree with @greggles in #1.

FWIW, the lack of an authentication system for third-party services on drupal.org (e.g., OAuth) is the fundamental root cause for the exaggeration in #2172149: Disable the Github Sync user account: it's confusing, and also the reason for why we need to think about a policy like this in the first place.

So, to some extent, circling back into the previous point.

3. Any information related to the modification must be included in the modification. Files related to the modified content must be attached to the node/issue/etc. they are related to; it is not sufficient to include a link to a file hosted elsewhere.

It's not really clear to me what is being meant by this.

Drupal.org should track all modifications by itself already, so why should the bot/tool/service duplicate that?

add patches with interdiffs to issues

Interdiffs are not a requirement. Some people would like to make it a requirement, but I couldn't disagree more. Interdiffs are posted for pure convenience. Not long ago, not a single issue ever contained an interdiff. If we always want interdiffs, then that is not to be enforced on contributors, but to be automated on drupal.org. (related)

Reverting bogus Conflict module conflict resolution.

Sending to the Technical working group queue, since https://www.drupal.org/node/2172149#comment-8420497 was sent there.

Technically, the path of least resistance at the moment looks like it will be lifting POST restrictions placed in front of the RestWS-generated pages, after testing. That would come with whatever authentication is baked in, or is straightforward to set up.

Thanks a lot for clarifications and adjustments, @greg.1.anderson!

re: kittens:

Looks like I was generally confused by the term "modification" (repeated 3x) ;) whereas it only presents the interaction context…

To some good extent, that topic is covered by filter.module + filter_html_image_secure.module already. What isn't covered are links to original art on external hosts (instead of attaching them), possibly including links to e.g. GitHub PRs (without attaching a patch).

For non-code interactions, there might be legit reasons for not attaching something but linking to it instead (e.g., licensing; all data on drupal.org is licensed under the GPL).

Your point that external services might disappear is a good one though. Perhaps we should rephrase it to say it's RECOMMENDED to attach data instead of linking to it?

(Every policy should follow RFC 2119.)

The oversimplified bottom line of this policy appears to be a single message:

An external service that performs non-idempotent operations on drupal.org MUST authenticate as the drupal.org user that triggered the operation, so as to associate all affected resources with that user. Non-compliant services will be blocked/banned from drupal.org without prior notice.

Thanks a lot for taking this on, Greg! Here's some feedback on the current issue summary (haven't read the comments so I can come in "fresh"). Since there are multiple 1s and 2s, I'm calling "Proposed Policies for Bots/Tools that Post on Behalf of a Human User Account" A and "Proposed Minimum Policies for System Bots" B for clarity.

A1. Can we please not use jargon like "idempotent"? :)

A2. If we're going to have such a rule, we should explain why. It forces developers to license their third-party tools as GPLv2+ which might drive developers away. (But maybe licensing is the reason this rule exists?)

But as a side note, it also seems fairly unrealistic; I highly doubt you're ever going to get Dreditor / Drush (two of the biggest potential consumers of such an API) to move back from Github to D.o, for example. At best, d.o will be a mirror of code that's primarily developed elsewhere. And if primary development happens elsewhere, most likely the server running the code for the bot is going to pull from elsewhere as well, and Drupal.org may only be updated on an "Oh, right, I should update Drupal.org" basis, so users actually get less visibility into what these bots are actually doing. :\

A3. This one seems like it's treading on dangerous ground. There's nothing in https://www.drupal.org/licensing/faq that says anything about linking to non-GPL "resources" absolves you from licensing issues (that word is way too broad). I would either eliminate this item entirely, or change it to simply state that the code must adhere to the standard d.o contributor agreement and link off to a canonical place for that info.

A4. I had to read this four times and I still don't understand it. Can we just say something like that the data you use in your script from Drupal.org can only be information that's publicly available? Or maybe cut to the chase and explain what are we trying to prevent here..?

A5. This seems overly specific to one particular use case (klausi's github script). Can we get to the root desire here? Is it to make sure you're not forging the identity or copying content of other users and posting it as your own? If so, say that.

B1. I get the gist of this rule, and agree, but don't understand how as a script author I would do that. Forge my author as "System message"? If so, say that. If not, it sounds like I need to make up my own user called "System foo" or whatever, but I'm sure that's not what you want. (Since that's what klausi originally tried and people freaked the hell out. ;))

B2. Specific permission from whom?

In general, I guess I feel like we're missing a "preamble" to this to provide some context (some of which is in the "how the rules apply" footnote). There's a lot of "insider baseball" in these rules as they currently sit. It'd therefore be helpful to "set the stage" a bit at the beginning, of some specific things we are trying to enable and actively discouraging to happen, but in general terms.

Maybe it helps to think along the lines of "personas" for who would be writing these kinds of scripts. Something like:

a) Hardcore D.o dev persona: This is someone who lives, eats, breathes, and sleeps on Drupal.org and is looking to write tools to speed up their workflow. drush iq, Dreditor, and alexpott's dopatchutils seem like suitable candidates.

b) External site dev persona: Someone who eats, lives, breathes, and sleeps on Github or StackExchange or Reddit. They want to integrate their service of choice with Drupal.org, but are more comfortable using external tools.

c) Vendor-neutral aggregator persona: Not sure what to call this persona, really. But picture you're someone from http://openhatch.org who is not affiliated with Drupal whatsoever, but is trying to come up with a central index of good open source issues for newbies, and wants to pull data from/push data to our API. Maybe that's just a variation of "External site" persona, not sure.

It sounds like what this policy is trying to do is encourage a lot of a), totally discourage any and all of b), and ??? on c). Though I'm not sure that's what's the most strategic for the project as a whole...

Ok, so let's get to the bottom of what people found objectionable about Klausi's script, since we seem to want to make avoiding those a focal point of this policy.

Here's what I remember of people freaking out about with github sync (feel free to correct any of my memories ;)):

a) Github sync "forked" developer activity into two places: drupal.org and Github. In order to get the "full picture" of what was happening on a given issue, you needed two accounts on two different services, or at least to manually click to some off-site URL. People feel strongly that Drupal.org should instead be the "hub" of development, and all development activity centralized here.

b) And it might've been one thing if it was only ephemeral in-progress code in throwaway branches that was over there, and once complete patches were synced over to Drupal.org (along with interdiffs), but there were also important "talky" bits as well; code reviews and the like, since Github's superior patch review interface is very enticing for people to use. In this respect it acted as a draw *away* from Drupal.org because it repeatedly drove traffic back to the external site.

c) Initially, the bot was acting like a human (posting comments, uploading code) but was doing so under a "system" account with no clearly identifiable information as to who was behind it and on whose behalf these comments/code were being posted. (This was subsequently changed to where it was posting as the actual d.o user of the person running the script (klausi).

c) I think is pretty adequately covered by the above policy. It makes a distinction between scripts automating tasks to make a human's work easier, and scripts automating "system" tasks.

For b) we could add something like a "no advertising" clause to forbid links to third-party services on behalf of bots? If there was no link back to the Github PR to comment on it, and it was posting as klausi the whole time, I don't know that anyone would've even put 2 and 2 together. (He could be doing this right now for all his d.o patches for all I know. :D) I dunno though. I feel like that might box us in too much... For something like drupalmentoring.org or PAReview, we might *want* that cross-promotion there.

a) Is definitely the most political / controversial of these things. It operates under the premise that Drupal.org "owns" Drupal development. However, that is not, in my estimation, correct. At least not anymore. And I don't know that "forcing" people to the mothership is going to materially improve the current situation, which is that D.o's dev tools have simply not evolved fast enough to keep apace of what places that have 80 devs and bazillions of dollars in funding to do nothing but write awesome VCS tools can do. And looking at the types of things the D.o tech team is taking on, which spans the gamut of everything *.Drupal.org does, not just dev tools, I don't really see that changing anytime soon. (There are still d.o sub-sites that are on Drupal 6, for example.)

So my concern with a) is it feels short-sighted to me, and out of touch with the way development actually works in the mid-2010s, and not something I'm totally comfortable with being enshrined in policy. It feels like a defensive throwback to "yesteryear" when Drupal.org *was* the central place where all development occurred. But nowadays, in many cases, Drupal.org is actually the last stop on the development train; a quick project publish at the end of a long development cycle in a Github repo, and external sites like Github and StackExchange is where most developers spend the vast majority of their time, whether on Drupal projects or otherwise.

So what is it exactly about a) that got peoples' hackles up? Was it having to have two accounts, one on an external service? The requirement to click to an external site? If so, then "aggregator"-like behavior actually seems like it would be a *welcome* thing to explicitly allow, rather than something we'd try and steer people away from. It would keep Drupal.org the "home" of Drupal development, but give people the freedom to work wherever they're most comfortable/productive.

^^ above barfing is personal musing only, not reflective of any of my other various hats, or even possibly my own personal opinion. :P

Next to the obvious user/masquerading/authentication concern (which doesn't require any further mentioning/discussion)…

From my perspective, the biggest concern was that there can be unlimited forks on GitHub and you are not able to track or follow them in any way - even though they may try to resolve the same canonical issue on d.o.

In other words, I think it's perfectly fine to use GitHub/Whatever/Whatnot for development purposes, and I even think it's fine to offload some level of reviews (especially nitpicks) onto such a service — whereas you should be prepared for late pushback in case you fail to communicate your work/progress "upstream".

However, the exact point where it melts down is that there can be forks of forks and PRs against PRs in an unlimited amount of arbitrary user repositories that you can't subscribe to ('cos you're not aware) - also, because there's no canonical Drupal GH repo you could subscribe to. (I'd strongly recommend to not subscribe to the current, because it's a mess. ;))

So, in the abstract, such usage ought to be fine, as long as you & others don't "overuse" it.

Unless I misinterpreted the original policy text, it tried to address that topic by establishing some rules about "fragmentation."

Hm. We already have that problem on Drupal.org with our own forks (sandboxes), though. There's absolutely no way anyone but someone with d.o DB access can tell you how many forks of core (or any other project) are floating around out there, unless they're advertised heavily. So not sure why Github would make that more or less bad.

Although. Quick shout-out to #1451668: Provide better integration of sandboxes and parent projects. ;)

Anyway, sorry, I got us off-topic and focused on one specific thing, which is the basic crux that we don't want discussions "forked" on multiple sites, because it creates a usability problem. So maybe we should make the rule more about that.

The only other thing I'd throw out there is we should challenge ourselves to think broadly about the use of this API, beyond just the issue queue. Here are some other possible use cases:

- Robot to automatically cross-post post Indeed/Monster/etc. Drupal jobs to jobs.drupal.org
- Robot to automatically cross-post d.o documentation pages for "answered" questions on stack exchange
- Robot to automatically cross-post themes that are created on Github under a certain user.
- etc.

Are these other "edge cases" adequately covered by the above policy?

Cool, I like that wording. Thanks, Greg!

FYI mglaman has a rather nifty little Chrome-based app that lets you monitor issues:

• https://github.com/mglaman/drupalorg-issue-tracker

mglaman is planning to add Kanban support to it, which would partially match what I've been doing in Trello (e.g. Panelizer issue list). Right now I have to manually curate all lists, but it'd be really awesome if it could ultimately control tags (or parent-child relationships).

Maybe access could be limited to e.g. people with specific roles, or only maintainers of a project could integrate with the data for that project?

Anyway, I wanted to share the above project and (hopeful) use case so they could also be kept in mind.

The tool MUST include all code resources on drupal.org; it MUST NOT link to code stored on external servers.

There are several issues with this "MUST":

1. Forces code to be open source, even if it uses licensed/proprietary code.
2. Forces code to be on d.o's infrastructure. Let's face it, d.o only has real support for PHP based "tools" and hell, we still don't even have testing for our themes...
3. Implicitly implies that there is going to be people "reviewing" code to ensure that it doesn't "abuse" something. Question, who's going to do that and isn't that a rather arbitrary notion in and of itself? Do we need to create another project review problem?

The reality is this: we'd simply block a user when we notice abuse is or has happened since they'd already have to be authenticated anyway using said tool.

So this means that if someone creates a user specifically for said tool and then everyone uses said user, that user would eventually get blocked. This would force the user to either rethink their tool/app, or force content to be created/modified by real users. Problem solved.

Yes, we may risk blocking valid users due to either bad or malicious apps/tools, however they can easily explain this and get their account reinstated with the promise that they'll stop using the app/tool or file a bug with said app/tool and wait for it to be fixed.

I would also say that we should require apps/tools to provide a unique user agent value.

This way, if too many users were to get "blocked" to no fault of their own, we can just blacklist requests from a specific user agent entirely and effectively kill an app/tool.

This is an exceptionally old issue to be necro-ing. However, it's relevant to a page I just put together...

As we start doing more with GitLabCI we want to enable people to do more with Peronal Access Tokens, which is more API access. This is a subset of all the ways people could automate/script/use bots on Drupal.org, but it's a concrete one I was at least able to write an initial policy for.

We should keep updating as specific use cases arise, and not be afraid to iterate on it if the language isn't perfect.

Also - the requirement to open an issue for approving an automation allows us to request things like a unique user agent string and some of the other requirements discussed above, where appropriate.

https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-dr...