Daniel Bachhuber 1:21 pm on July 5, 2017
Tags: cli ( 2 )

How should we embark upon new feature development?

Update July 11th: We’re having a follow-up discussion in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. (#cli channel) next Tuesday, July 18th at 16:00 UTC (9 am PT, 12 pm ET). Our goal is to get to the point where we have a rough sense of the path forward.

The WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ package index is a directory of user-maintained commands. For a long while now, submissions have been put on hold. I’d like to unblock new feature development, but we first need to address the conundrum before us.

Originally, the package index was created as space for developers to share custom WP-CLI commands. A developer would write a new command, submit it to the index, and the command would be displayed on the website for others to discover. The command would also become installable through wp package install.

However, the package index suffered from the same problems that plague the WordPress pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party directory:

After a while, submitted packages are no longer actively maintained. Eventually, they become abandoned. Maintaining packages is commonly a solo-author activity when it needs to be a multi-author activity to be sustainable.
Over time, different implementations are submitted of the same feature. I actually ended up pausing acceptance of new packages when four of five submissions were near duplicates of existing packages.

Just like WordPress, the end-user experience is the priority for the WP-CLI project. It’s a bad user experience to have to choose from multiple poorly-maintained implementations of the same feature. It’s a much better user experience to have one high-quality, well-documented solution to a specific problem.

Not only that, but we’d much rather focus contributor effort towards maintaining common packages, rather than have spread amongst a number of one-off individual implementations. The maintenance burden of the command ecosystem is much easier to manage when somewhat centralized, than spread amongst numerous small projects.

Given what we know at the moment, our priorities are the following:

Provide an outstanding user experience.
Have a streamlined pipeline for adding needed functionality.
Be able to maintain and adopt packages to keep them available for the community.
Keep maintenance effort in check.
Encourage contributions in many forms.

What we want to avoid is any of the following:

Outdated / abandoned packages being endorsed to users.
Duplicated functionality causing confusion.
Maintainers being a bottleneck.

We were fortunate enough to be able to discuss this problem during the WordPress Community Summit. Brainstorming with other community members, we were able to identify three possible approaches so far:

A. No package index, but community-driven feature development.

Ideas are collected within the wp-cli/ideas repository or a similar tool. The ones that get the most traction or votes get included in the roadmap to build as new official packages.

Observations from the discussion:

Solves problems noted above by having WP-CLI be the sole source of endorsed packages.
Not practically feasible in terms of team effort.
Too slow to make progress and act on requirements.

B. Submission proposal that is coupled to precise quality and maintenance requirements.

To get included in the package index, you need not only ensure high quality but also commit to regular maintenance.

Observations from the discussion:

Adds strict procedures and requirements to the current package index.
Could include the provision that abandoning a package will cause it to be adopted by the WP-CLI project itself.
Growing team effort that will become problematic over time.

C. Two-tiered system with both an “official” index and a “community” index.

The “official” index is controlled and endorsed by the WP-CLI team, while the free-for-all “community” index will include a notice that use of these packages is at everyone’s own risk.

Observations from the discussion:

Completely open directory is valuable for innovation.
Submissions could default to the “community” index, and packages then need to submit a proposal to get “promoted” to the “official” one if they meet the requirements.
Adds cognitive overhead by having two sources of packages, with potentially two different mechanisms of installation.

None of these three approaches is a perfect fit for our priorities above, they just provide differing sets of benefits and drawbacks. In addition, we are quite sure there are other models out there that can potentially be adapted to meet our needs.

This is where we are hoping for valuable input from the community. There are some specific decisions we need to make:

What process should we follow for new feature development?
Is it possible to adapt the existing package index to help us achieve our priorities?
If yes, what form should it take?
If no, is there another mechanism might we employ?
What should we do with the pending submitted packages?

Have some perspective to share or process to suggest? Know of other projects that we can model our approach on? We’d appreciate your comment on this post, especially if it also includes pros, cons, expected maintenance burden effort, etc.

Please keep in mind that we may make a decision you don’t agree with. Our decision will be biased to reflect the priorities of the project.

We greatly welcome your input to the decision-making process, though, particularly to the degree that it’s respectful, introduces perspective we may not have considered, and represents a great deal of thought and consideration.

#cli

Darren Ethier (nerrad) 4:19 pm on July 5, 2017
I appreciate the thought and work going into addressing this problem, it certainly is an important one to resolve. My reply to this post is for the most part in response to this:

Just like WordPress, the end-user experience is the priority for the WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ project. It’s a bad user experience to have to choose from multiple poorly-maintained implementations of the same feature. It’s a much better user experience to have one high-quality, well-documented solution to a specific problem.

I think it’s important to keep in mind that the “end-user” for wp-cli is much different than the end-user for WordPress plugins. As such, I don’t really see wp-cli packages being comparable to WordPress plugins in terms of implementation and user experience. I think a more appropriate comparison would be to compare the wp-cli package index with npm or packagist.org. When I first started using wp-cli that was my immediate thought when I came across the wp-cli package index.

When I use packages from npm or packagist in my projects, it’s after evaluating whether I can “trust” that implementation long term or not and if not, I just stop using/don’t use it. I think with the appropriate communication, it’s reasonable to expect end-users of wp-cli to use any wp-cli package index similarly.

With that in mind, my response to the requested feedback:

What process should we follow for new feature development?
- Build/implement a similar hosted package index like packagist and npm. For now I think its reasonable to have the existing GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ repo serve as this.
- Modification of existing/creation of new public index of packages that builds from the info available on package repos. Include info in this public index that helps end-users make an informed decision regarding the state of the package.
- require the composer.json file (or maybe a new wp-cli-package.json file to have a namespace key. This allows wp-cli to reserve its official command namespace and to allow multiple implementations of similar behaviour if someone has a different idea on how a similar command should work. wp-cli coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. would then register that package with that namespace key so all commands for that package must be executed with wp {namespace} {command}. You could have exceptions for official wp-cli packages. Once a namespace has been registered for a package only “owners” of that namespace (owner being whoever originally registered a package with that namespace) can submit new packages using that namespace.
- Anybody wanting to add additional options/arguments to existing official wp-cli commands will be required to do pull requests/contribute to the official package repo for that command.
Is it possible to adapt the existing package index to help us achieve our priorities?
If yes, what form should it take?

Yes I think so, see my answer to the previous question. If needed you could create a bot to help check for requirements in the package.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. to automated the submission process. Eventually it might be beneficial to follow a similar submission process as what packagist or npm employs for their packages.

What should we do with the pending submitted packages?

Once a decision has been made for how packages are submitted, inform authors of pending submitted packages of any changes in the process.

How does this address concerns?

Two concerns were outlined in your post:

After a while, submitted packages are no longer actively maintained. Eventually, they become abandoned. Maintaining packages is commonly a solo-author activity when it needs to be a multi-author activity to be sustainable.

If you look at NPM and Packagist, the majority of packages hosted there are solo maintained. I personally don’t see this as a problem for long term longevity of the wp-cli core project provided there is sufficient info provided to the end-user to make their own evaluation on whether they want to use a package that doesn’t seemed maintained. In fact, one could argue that someone might see a package that isn’t maintained, really like it, and then fork it (if they can’t even get action on a pull request) and submit their own package (but obviously under a new namespace). It provides a way for abandoned projects to potentially be quickly picked up by others that are able to use the original as a starting point.

Over time, different implementations are submitted of the same feature. I actually ended up pausing acceptance of new packages when four of five submissions were near duplicates of existing packages.

I think this could easily be resolved by implementing the namespace requirement that I suggested. Again similarly to npm and packagist, I don’t think its a problem if there are multiple implementations of the same command behaviour. One reason this might have occurred is because of the delay in accepting the packages and thus authors not being aware of others work. In the end I think its actually advantageous to have multiple namespaced implementations of the same commands for end-users to try/pick from.
Ansel Taft 7:52 pm on July 5, 2017

Given the proposals I think C is the cleanest choice, that packages can graduate to an official tier.

I would also like to see some sort of ‘package available for adoption’ status, to help the future situation when a developer no longer has time to maintain the code. There’s a correlation in the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party world for this, though it’s not officially supported (apologies for linking to the Google search but more than one article was written about this):

https://www.google.com/search?q=wordpress+plugin+adoption

It would be nice if WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ planned in advance for this inevitability and had an official route unlike the plugin repository.

Cheers
dmccan 10:12 pm on July 6, 2017
I would suggest defining up-front what an “abandoned” package is. For example:
- No update in over a year (updating the readme with last tested date would be OK).
Or
- Bugs confirmed by more than one user and not addressed in X amount of time.
Hoover 2:35 am on July 7, 2017

Of the 3 options, I greatly like C the best. It feels like a good balance between encouraging new contributors (as they can get listed easily) and providing high-quality packages that are clearly identified (through featured packages).

Two good models for this could be WordPress’s featured plugins or NPM’s Most Depended Upon packages. WordPress is maintained by humans while NPM works off of analytics of package usage. Either or a combination would help to bring the best wp-cliWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ packages to the top.

My personal opinion is that many (most?) wp-cli packages will develop for niche or special cases rather than coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. contributions. I hear fellow developers talking about how to extend wp-cli to do X task that they need done routinely. In such a situation, a broad/flat repository would be more useful than a curated one.

Echoing what nerrod said, the nature of the package game seems to be that they have a single contributor. I would love to see a prominent way to encourage others to help maintain existing packages (keeping all packages in the WP-CLI GitHub would make adding and replacing contributors easier, as you wouldn’t have the main contributor ghost on you.
Ulrich 6:40 am on July 7, 2017

The WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ Theme and PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party repos have this problem too.

I think most people can figure out if a package is maintained or not.
Add the last updated date would be useful and also allowing packages to define if it has been tested with the latest version of WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/.

An example of three packages doing nearly the same thing.
https://github.com/diggy/polylang-cli
https://github.com/exozet/wp-cli-polylang
https://github.com/dereckson/wp-cli-polylang

The discussion to collaborate did not go far. https://github.com/dereckson/wp-cli-polylang/issues/5

A fully managed package library will be extra work which is not always worth it.

Maybe find a way to encourage people to collaborate more with each other. If you want your package to be added to the list it would need to be moved to WP-CLI organisation. This would allow easier handovers if the code is not being maintained instead of forking the project.
Daniel Bachhuber 4:37 pm on July 11, 2017

Thanks for the input so far, everyone.

Just to let you know, we’ll be discussing this in real-time next Tuesday, July 18th, at 16:00 UTC (9 am PT, 12 pm ET). The goal of the discussion is to get to a point where we can draft a proposed policy document, detailing the specifics of the package index / new feature development.
Takayuki Miyauchi 6:34 pm on July 11, 2017

I really appreciate your hard work!

I think C is the best.

I am hoping that package index should be like NPM or Composer repository, but I know there are some packages that are no longer maintained.
And I can understand that it isn’t good user experience.

I have some packages listed in package index.
Some packages are developed for our service (e.g, https://github.com/getshifter/wp-cli-shifter), and some packages are for our open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project (e.g, https://github.com/vccw-team/scaffold-vccw).

Those packages are developed for special cases, and developed by small team.
I know those packages should have 2 or more maintainer, but it is difficult for us and those packages are really important for us.

However, I have a package that is not maintained a long time.
I hope wp package remove command will be added.

Anyway, can composer check the package version before install?
If wp package install can check the version number of the new package, wp-cliWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ will be able to stop installing the package.

Thanks!

Welcome to WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/!

Contact

How should we embark upon new feature development?

Welcome to WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/!

Contact

Share this: