BP REST API chat summary – Jan 28, 2019

See previously: https://bpdevel.wordpress.com/2019/01/23/bp-rest-api-chat-monday-jan-28/

In attendance: boonebgorges, espellcaste, imath, rekmla, tw2113, chetansatasiya Slack archive: https://wordpress.slack.com/archives/C02RQBYUG/p1548687725147600

We chatted briefly about the current state of the API code https://github.com/buddypress/bp-rest. CRUD coverage for BP content types is about 90% complete, with a few pending PRs. Renato and Boone are working toward 100% in the next week or two.

There was general agreement that the BP 5.0 release should focus on the REST API, with a tentative date of Q1 2019 suggested. A few discussion points:

Documentation

Questions about API usage have already come in at a fairly fast pace on the GitHub issue tracker. As such, we aim toward having documentation covering basic usage by the time we ship. For reference, the WP REST API documentation on developer.wordpress.org contains both hand-built documentation and automatically generated docs. See https://developer.wordpress.org/rest-api/ and https://developer.wordpress.org/rest-api/reference/. We’re hopeful that we can leverage some of wordpress.org’s tools for automated generation of documentation, or perhaps a third-party tool like https://github.com/humanmade/Restsplain In the upcoming weeks, we’ll try to collect team wisdom on the current state of buddypress.org and the options available to us.

If it’s not possible to make major mods to our wordpress.org documentation in order to support these automatically-generated docs, we might roll our own outside of wordpress.org, much in the manner of https://wp-api.org prior to the core REST API merge.

Authentication

Authentication is likely to be a point where documentation is especially important, particularly because the majority of BP site users are authenticated. There have also been some questions on the GitHub repo about the consistency of making authenticated requests, the use of nonces, etc. For reference, here’s the core page on API authentication: https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/

BP core API usage

There was general agreement that it’d be wise for BuddyPress itself to use the API in at least a handful of ways for the 5.0 release. In addition to enabling new, AJAX-powered interfaces, the process of building on top of the REST API for BP itself will help the team gain familiarity with the nature of the API, and improve its usability before the public launch.

In some cases, existing AJAX can be converted to use the API. See eg https://buddypress.trac.wordpress.org/ticket/8043#ticket. In other cases, we may consider adding new interface features using the API. See eg https://buddypress.trac.wordpress.org/ticket/8045#ticket. While it’s generally safest to modify existing functionality in the Dashboard – where our interfaces aren’t easily customizable by themes etc – it may be possible to swap out some front-end stuff (say, in Nouveau) without too much breakage. My initial thought was directory AJAX, but then I remembered that some of those existing endpoints return markup rather than JSON-formatted entities. Any ideas are welcome.

Ongoing meetings

In support of the 5.0 push, we’d like to reestablish regular project meetings. The current proposal is to use the old meeting time of Wednesdays at 19:00 UTC, every other week beginning February 13.

#5-0

BP REST API chat, Monday Jan 28

We’ll be having an informal chat in the #buddypress Slack channel at 15:00 UTC on Monday, January 28 to talk about BuddyPress 5.0, and especially next steps for the BP REST API project https://github.com/buddypress/bp-rest. This will likely lead into some broader discussion about BP focuses for 2019. I’ll post an update here afterward for those who are interested but unable to attend.

BuddyPress 5.0.0 will require WordPress…

BuddyPress 5.0.0 will require WordPress 4.7 or greater. See https://buddypress.trac.wordpress.org/ticket/8025, as well as the perennially ripping read, https://codex.buddypress.org/getting-started/wordpress-version-compatibility/.

BuddyPress 3.1.0 is now available!

BuddyPress 3.1.0 is now available. It includes 23 bug fixes. See https://buddypress.org/2018/06/buddypress-3-1-0-maintenance-release/ for more information.

Note that there may be some manual adjustments you will need to make to fix some outstanding issues.

BuddyPress 3.0.0 “Apollo” is now available!

BuddyPress 3.0.0 “Apollo” is now available for immediate download from the WordPress.org plugin repository, or right from your WordPress Dashboard.

Read all about it at https://buddypress.org/2018/05/buddypress-3-0-0-apollo/

Check out the changelog for more information https://codex.buddypress.org/releases/version-3-0-0/

BuddyPress 2.9.3 is released: https://buddypress.org/2018/01/buddypress-2-9-3-security-and-maintenance-release/

BuddyPress 2.9.3 is released: https://buddypress.org/2018/01/buddypress-2-9-3-security-and-maintenance-release/

Our Awaiting Contributions milestone contains…

Our Awaiting Contributions milestone contains 480 tickets, of which 141 are classified as bugs, with the rest (339) as enhancements. I propose that we close ~260 of enhancement tickets to help make our project more sustainable.

In a recent post, I announced some Trac workflow changes, and alluded to a problem with the “Awaiting Contributions” milestone.
Any bug report that the project hasn’t fixed in a release, or feature suggestions we haven’t implemented, or those that we hadn’t made a decision on whether to implement or not, have eventually ended up in the “Awaiting Contributions” milestone. This milestone tends to be one-way; relatively few tickets have ever made it out into an actual release.

260 of the 339 “Awaiting Contribution” enhancement tickets have not been modified since December 2016 (see list here); this means no edits, no patches, and no comments.
I believe this is because the enhancement tickets have a variety of relevance: some are good ideas that fit the project, some are good ideas but perhaps don’t fit the project any more, and some are ideas that might fit the project better in the future. Very few people know which new features might be accepted today. Historically, we have not had the discipline and the right processes in place to make hard decisions.

Are good ideas still valuable even if no-one has wanted to work on them, years after they were shared? Of course they are, but more importantly — more realistically — we will never be able to implement even a small percentage of these enhancements. We would not be saying “no” to the ideas, just being honest with ourselves and recognising that is unlikely that we will ever have enough people to implement them.
There is a psychological backlog to this number of tickets; it’s a weight on our shoulders, and for the average WordPresser, it might suggest that the project is not actively maintained.

I suggest we close these inactive enhancement tickets so we can start over, and repeat this process every year. Yes, it’s a cull. The enhancement tickets from 2017 onwards are recent enough that they might be more relevant than the older tickets, and few enough that we can thoroughly re-review these over the year ahead.

I am not proposing to close the bug reports in the “Awaiting Contribution” milestone, as they merit re-review. If I felt inclined to fix a bug, it’d be great to have an audited backlog of bug reports to pick from, with the confidence that they are still relevant, and that they contain enough direction on how they should be fixed, to be sure that my contribution would be accepted by the project.

Regular contributors, I’m looking forward to your feedback.