A Developer resources site before the 5.0.0 release?

During our latest dev-chat, we’ve been talking about putting together a documentation site for the BP REST API. I’ve been exploring the subject more deeply this week and I believe we should take this opportunity to try to ship a first version of the developer resources site.

I think 5.0.0 is an interesting time/release (as it’s a very developer oriented one with the inclusion of the BP REST API) to start powering BuddyPress developers with some resources just like WordPress does with its DevHub project.

The « BP » DevHub project?

@tw2113 started working on a BuddyPress Code Reference site 3 years ago, see #6812. In his last comment he expressed his concern about the lack of developer content the site would offer. Then I thought the BP REST API documentation could be a great companion to this BuddyPress Code Reference! So I’ve carried on his work and built a local test site to check how difficult it could be to make this real.

Screen capture of the BP DevHub homepage
Preview of the homepage of the Developer resources site.

It’s doable before the 5.0.0 release!

It took me a couple of days, following and adapting the installation steps described in this chapter of the WordPress Documentation handbook, to build a « proof of concept » framework. Actually all I had to do was to create a child theme for the « wporg-developer » theme and share 2 patches on the Meta Trac (see #4516 & #4517) so that the Meta Team could fix the 2 issues I’ve found during my explorations.

Here’s what we need to do on the existing developer.buddypress.org site :

  1. Make sure Composer and WP CLI are running on the server.
  2. Install the « wporg-developer » theme.
  3. Install the WP Parser plugin → composer create-project wordpress/phpdoc-parser:dev-master --no-dev & activate it.
  4. Install & activate the Syntax Highlighter plugin.
  5. Install/Build the latest version of BuddyPress 😍 (no need to activate it).
  6. Run the WP CLI command using the BuddyPress directory of point 5 as the argument. For example: wp parser create path/to/wp-content/plugins/buddypress --user=1 or wp parser create path/to/wp-content/plugins/buddypress/build --user=1 if trunk is used.
  7. Install & activate the Handbook plugin (We don’t need the wporg-markdown & wporg-cli plugins as we don’t write our documentation on GitHub and moreover it would import the WordPress REST API and Coding standards documentations).
  8. Install & activate the « bporg-developer » child theme I’ve built using the Customizer live preview (so that it automatically creates the starter content – make sure the fresh_site option has its value set to 1).
  9. Go to the General Settings Administration screen and insert the version of BuddyPress into the BuddyPress latest stable version option.

Wait, but what about the BP REST API Documentation?

If you’d go on the BP REST API Handbook at this stage you wouldn’t see any content. We need to create it. We chose to have it generated thanks to the REST schemas of our REST endpoints. The Restsplain plugin does this task for all the WordPress and custom endpoints of the website.

Using it as it would first mean to activate BuddyPress (and possibly the BP REST plugin if not yet included into BuddyPress).

There are benefits of having the generated documentation this way as new endpoints would automatically be included. It’s also possible to create and attached content to our endpoints using the post type included inside the plugin. But there are also disadvantages: 

  • All BuddyPress components would need to be activated.
  • The React Application inside the Restsplain plugin is displaying the real URLs at various places.
  • It is also including a feature to use them into a specific container to make real REST requests.

The good new is: we can filter the list of endpoints the Restsplain plugin is generating. So I’ve added this filter to the bporg-developer theme and the documentation generation is now restricted to BuddyPress endpoints. Then I thought we could avoid the need for BuddyPress to be activated by first looking for an external Json file (a static copy of the array expected by Restsplain, where links are « anonamisized »).

But still, I had to remove completely the live testing of endpoints feature. Although it can be done in CSS, I chose to edit the plugin because:

  • it has not been updated for 7 months and as a result contains outdated node modules and React library.
  • Some real links are built in React using the rest base URL.
  • One of the link of the React endpoint viewes is triggering the live testing.

As a result the version of the plugin I suggest to use is the fork I’ve made here. As I’ve edited the React part, I also edited the styles to match the BuddyPress.org colors. Here’s how it looks:

Screen capture of the "api docs" page

As you can see it’s very different from the output made by the WordPress handbook plugin. The best I could do to make it more looking like it was to use the [restsplain] shortcode in a page.

Screen capture of the shortcode used in a page

That’s why I think we should probably only use this plugin to write a static version into the BP REST API handbook post type of what it generates dynamically.

We have 14 endpoints to document for 5.0.0 and 8 others for the 6.0.0 release and I think we can do some copy/pasting:  it won’t take too much time and the layout of the documentation will be the same for every potential handbooks (eg: BuddyPress plugins or themes).

Moreover we’ll be able to improve the navigation grouping endpoints by components, we’ll be able to use more meaningful titles for the GET, POST, PATCH, DELETE methods, eg: Get a specific user, add a user, update a user and remove a user. Finally we would be able to use code examples using our bp.apiRequest function instead of the fetch function Restsplain uses. Below is a screenshot showing what I mean about this copy/pasting task.

Screen capture of a potential page of the BP REST API handbook

What if we’re running out of time building the developer resources site?

It would be too bad, but not a so much big deal! I’ve already created a documentation site for the BP REST API. You can test it here. We would simply need to attach to this site a more meaningful domain name 😉

And when/if we get the developer.buddypress.org site ready (See the 9 steps above) soon enough we’ll be able to use this website to do the copy/pasting tasks.

Let’s discuss about it during our next dev-chat!

As a reminder, it will happen this Wednesday (June 26) at 19:00 UTC into our Slack channel: #BuddyPress. All BuddyPress Contributors are very welcome to join us. If you’re a bit intimidated (you shouldn’t!) but still want to give us your opinion about this topic, please use the comments area below 👍

#5-0, #developer-documentation

Dev Chat Summaries for May 24 & 31, 2017

bp-nouveau

@hnla gave an update of the work done for the past two weeks:

  • Improved Group invites screen
  • Updated the search styling/markup to match to directory search input
  • Improved general styles and icons
  • Updated the action button for groups and activity arg functions to better check and switch the url nonces from href to data attr depending on element selection.
  • Tweaked JS to ensure we target correctly the newer elements so screen messages display within grid loop boxes
  • Added Ajax support for state changes
  • Changed a range of action links to button elements
  • Added missing labels for form controls
  • Merged pull requests from new contributors, @jon007 & @s-ferdie, for cover-image-header correction and adding parameters to allow Sass variables to be overridden.

Trac Tickets

Remove `remove_node` ‘edit’ in `bp-core-adminbar.php` (#6831) @tw2113 has committed patch to trunk.

Remove/Replace `title` attributes with Tooltips usable in all devices (#7188) Screenshots on Mac OS for latest patches posted by @dcavins. Feedback from @hnla. @r-a-y recommended using `data-bp-tooltip` instead of `data-title`. @mercime will refresh patch and commit.

Only load component action and screen code when we’re on the component’s page (#7218) @r-a-y has patch. @boonebgorges has posted feedback.

Don’t show the sorting box and the meta information (#7312) Related: #6754.

When user is not logged in, in he/she clicks email link to view new messages gets 404 page when should get login page (#7349) @r-a-y has committed a couple of patches fixing redirection issue and adding notices. Has new patch for `visibility` and `redirection` updates.

Fix for profile image upload on Microsoft Edge breaks iOS Safari and Chrome (#7416) @r-a-y has patch. Needs iOS user to test. Update: @mrjarbenne has tested patch and the issue still exists on Mobile Safari on iOS.

Resize member avatar error with cyrillic (not latin) filename (#7484) @r-a-y has patch. @boonebgorges: “I’d have to spend more time with it to understand in greater depth, but at a glance it looks like a clever fix.”

`bp_group_has_members` performs unnecessary query (#7513) @dcavins has patch. Dev feedback requested.

Messages are not deleted from DB, when user is deleted (#7523) @r-a-y has refreshed patch based on discussion during dev chat.

Counter for “All” tab for activity and groups table (#7526) @bhargavbhandari90 has patch. @r-a-y will review the patch.

Fetching of ALL users from `bp_friends_prime_mentions_results()` for non logged in users (#7530) @r-a-y has committed patch to trunk.

Slack logs:
May 24: https://wordpress.slack.com/archives/C02RQBYUG/p1495652618137375
May 31: https://wordpress.slack.com/archives/C02RQBYUG/p1496257388695772
(A WordPress Slack account is required to view the logs.)

Dev Chats as of March 15, 2017

BuddyPress 2.9 Schedule

  • March 22 – Kick off
  • June 7 – Beta 1
  • June 14 – Beta 2
  • June 28 – Release Candidate 1 – String freeze
  • July 5 – BP 2.9.0 Target Release Date

@hnla, BP 2.9 Release Lead, looks forward to discussing project scope/focus/tasks with the team on March 22.

Dev Chat Schedule

Daylight Savings Time for the United States started Sunday, March 12, while DST in Europe will begin on March 26. In keeping with schedule adjustments from previous years, following is the schedule of our dev chat till further notice:

  • March 22 – BP Dev chat will remain at 20:00 UTC (4:00 P.M. EST / 1:00 P.M. PST for U.S. residents).
  • March 29 through end of DST – Dev Chat will be moved to 19:00 UTC.

BuddyPress.org Redesign

  • The redesign of BuddyPress.org has been discussed many times over a number of years.
  • Feb. 22: @modemlooper initiated discussion this year about BuddyPress.org colors, adding a showcase page, work on the product side, among other things. He also posted some screenshots on that day and following days to ask for feedback.
  • March 6: @modemlooper set up a responsive demo site.
    March 6 - modemlooper initial design
  • March 15: @karmatosed uploaded her design  during dev chat. She mentioned @djpaul asked her to look at a BuddyPress.org redesign last year.
    March 15 - karmatosed design
  • Other notes:
    • Redesign is also needed for codex.buddypress.org plus a new design for developer.buddypress.org to hold the BP developer reference which @tw2113 has on his site https://trexthepirate.com/buddypress/
    • BuddyPress.org themes are located at https://meta.trac.wordpress.org/browser/sites/trunk/buddypress.org/public_html/wp-content/themes

Slack log: https://wordpress.slack.com/archives/C02RQBYUG/p1489608197865211

#dev-chat

Dev Chat Summaries for December 21 & 28, 2016

BP 2.8 Trac Tickets

BP 2.8 – Prevent loading if PHP < 5.3 (#7277) @boonebgorges has patch. Dev feedback requested (esp. @johnjamesjacoby & @djpaulgibbs).

Removal of `create_function` usage for BP 2.8 (#7325) @tw2113 has patches.

Anonymize BP Core Dependency functions file. (#7335) Closed as wontfix.

`groups_promote_member()` shouldn’t attempt to fetch ⁠⁠⁠⁠BP_Core_User⁠⁠⁠⁠ object (#7382) Patch needs unit tests. Assigned to @boonebgorges.

Add a “buddypress” class to body element of wp-admin (#7353) @slaffik has committed fix to trunk.

Component Maintainers

@slaffik will be contacting everyone who volunteered to maintain BP components in Trac.

@dcavins would like notifications from Trac for new tickets under the Group components. He mentioned different workarounds like getting Slack notifications for the Groups component to getting the RSS feed from Trac for the specific component. @johnjamesjacoby: “We’d need to merge into our Trac what’s already in WordPress Trac. That’s probably Dion and/or Nacin.” @netweb noted after the chat that there’s a ticket in Meta Trac to get this underway.

🥂 Wishing Everyone a Happy & Prosperous New Year! 🥂

Slack logs:
Dec. 21 https://wordpress.slack.com/archives/buddypress/p1482350517001398
Dec. 28 https://wordpress.slack.com/archives/buddypress/p1482955219002247

#7277, #7325, #7335, #7353, #7382, #dev-chat

Dev Chat Summary for November 2, 2016

BuddyPress 2.7.2

@johnjamesjacoby packaged and released BuddyPress 2.7.2 on November 4, 2016. This is a maintenance release and a recommended upgrade.

BuddyPress 2.8.0

Schedule

  • January 4, 2017 – Beta 1
  • January 18, 2017 – Release Candidate 1 (string freeze)
  • January 25, 2017 – Target release date

@slaffik, the 2.8 Release Lead whose “developer heart loves things like PHP5.3+ and changed focus in development”, would like to focus on the following:
1. Components with highest tasks number – because people care about them the most
2. Components with lowest tasks number – because they are good candidates to become 0-tasks, which is cool for Trac health
3. Working UI for developer features started development in 2.6 and 2.7
4. Security – He will dive into this topic as he developed a huge interest recently and will do an audit.

His ultimate goal is to decrease the number of tickets (650+) in Trac by 50%. Responding to @boonebgorges‘ question how he planned to meet that goal aside from own labor, @slaffik wrote that he is looking into implementing the concept of BP Component Maintainers which @offereins volunteered to set up a few months ago at Google Docs.

@djpaulgibbs cautioned, “I’m not sure most of the tickets in the Future Release milestone have been looked at in a long time, and I bet most of them are not assigned to the best Component (many probably pre-date the current lists of Components) so maybe we want to review them all first.”

@slaffik also would like to see improvements made on BuddyPress.org and codex.buddypress.org “but first I need to install all that locally and play a bit and see how things are working.”

developer.buddypress.org
@dcavins: “I’d love to see the new documentation site @tw2113 has been working on go public.”
@tw2113: “Regarding the dev site, a lot of me wants to say let’s get it set up and manually run for now, and we can work on automation later on. Perhaps get it logged in only access at developer.buddypress.org and have everyone start doing final QA.”

Caching improvements
@boonebgorges: “I don’t have any particular pet projects in mind for 2.8, but I plan to be around to help with miscellaneous stuff. Maybe more caching improvements.”

Build tooling, Behat, wp-admin area
@djpaulgibbs: I’m planning to help iterate on the build tooling. And continue to work on a test suite around Behat, which I’ve been doing for the last 3 months, but I don’t know if it’ll get ready enough in time for 2.8 consideration. Also the wp-admin area / welcome screens, @mercime and I have discussed them a bunch in a past. There’s so much we could do there. Maybe that’s something we could look at.”

BuddyPress Types UI
@boonebgorges: @dcavins started work on admin UI for group/member type creation. I’ve started to dig into it myself, and that could be a good kickoff for improved wp-admin stuff.
@dcavins: The first-draft code so far is publicly available at https://github.com/dcavins/bp-types-ui. Once @boonebgorges has worked it over, I imagine it will move to its original repo at https://github.com/buddypress/bp-types-ui.

Accessibility
@mercime: On my end, work on improving accessibility continues. Btw, one survey participant thanked us for a11y improvements. @boonebgorges: The a11y improvements are huge – aside from being the right thing to do, they also make it easier to sell BP with confidence to organizations that are legally required to meet certain a11y standards.
@mercime: There’s lots more to do, but it can be done. The most challenging area would be the xProfile draggable fields in wp-admin, I will do that last.

BP REST-API
@boonebgorges: “I have been working with @bronsonquick to work up a kickoff for the project. It’s been slow going because of scheduling issues between the two of us. I would like to do a public kickoff in the next few weeks, even if I have to prep the documents myself. We have some ideas for a proposed outline and work plan, which we want to bring to the community for feedback.
“Phasing in support over several releases. Prioritizing certain components and prioritizing read vs read-write with an eye toward selecting a couple of projects as good first implementations (which will guide the endpoint strategy). Anyway, I’ll work on getting that initial document ready, and then I’ll work with @slaffik to schedule a meeting where we can talk about the path forward. The purpose of preparing a document is just so we have a starting point for conversation – all the decisions will be made in the open.”

BP Follow, Component Loading
@rayisme: “For 2.8, I’m keen on #7218 for the time being. There was a ticket talking about folding BP Follow into Core, which I’ve been meaning to reply to (and will), but there are a couple of technical ideas in BP Follow that conflicts with other tickets.”

2016 BuddyPress Survey for Site Builders and Developers

The survey is will be open till November 30, 2016. Some updates from those who have responded so far:

  • Six survey participants have already expressed interest in sharing how they are using BuddyPress.
  • All respondents are using PHP versions 5.3 and above.
  • One respondent appreciated accessibility improvements.

@johnjamesjacoby noted, “I like the idea of putting the survey front & center on BuddyPress.org, the same way WordPress.org does.” @mercime will prepare patch for the survey banner.

Your feedback is most welcome! https://buddypress.org/2016/11/2016-buddypress-survey-site-builders-developers/

Slack log: https://wordpress.slack.com/archives/buddypress/p1478113373000026

#7218, #dev-chat

Dev Chat Summary for September 7, 2016

BuddyPress 2.7

Trac Tickets

Groups query overhaul (#5451) @boonebgorges has patch to boost performance and object caching for the Groups component. He noted, “There will be some backward compatibility breaks for anyone using `bp_groups_get_(paged|total)_groups_sql` filters and has listed some plugins in ticket. Dev feedback requested –  especially @djpaulgibbs and @rayisme ( @dcavins has already voiced his support 🙂  )” @rayisme has posted support as well. Update: This is now in trunk.

Hierarchical groups (#3961) @dcavins is ready to commit the patch which has a cache invalidation scheme. @boonebgorges said patch looks good and mentioned testing the patch with thousands of groups. @dcavins is prepared to test with a group generator via WP-CLI.

Friends: Add caching to BP_Friends_Friendship class (#6978) @dcavins has refreshed patch which caches friendship objects separately from a users’ friendships.

Change bp_sort_by_key() to allow key preservation (#7238) @dcavins has patch, “If anyone has reservations about changing the underlying function call, please add a note on the ticket.”

Add action hook(s) outside the group admin form (#7249) @dcavins has patch. @boonebgorges, “seems fine to me.” @tw2113 “is fine to me too, it has its docs.” 😀 Update: This has been committed to trunk

No group members search in groupname/admin/manage-members/ (#6385) @dcavins has patch. Dev feedback needed.

Improve group management members screen (#7105) @dcavins has patch. @boonebgorges has posted comment in ticket. Update: This has been committed to trunk

Update BP_buttons class to accept new arg param for $element_type (#7226) @r-a-y requested feedback for current patch.

Group type frontend integration (#7210) @rayisme noted in ticket that he was going to commit patch soon. This has @boonebgorges‘ ♥ stamp.

Only load component action and screen code when we’re on the component’s page (#7218) @rayisme has patch. Dev feedback requested for relocating functions.

Screen notifications settings page (#6712) @rayisme has patches for a separate screen notifications panel as well as for a new merged notifications (email and screen) panel. @dcavins likes the “idea of a central place to manage communication.” @boonebgorges “I haven’t tested the patch, but I definitely like the idea of a central place for managing this stuff. I’ll check it out. What to do with 3rd-party settings doesn’t seem like a dealbreaker either way.”

Use WP page names for BP directory pages headings (#6765) @hnla requested dev feedback. @boonebgorges will look into this.

Display and filter by member type on Dashboard > Users (#6060) @dcavins has updated patch. Dev feedback requested – “a lookover would be great because this should easily apply to the groups wp-admin table with slight modification.” @boonebgorges will try to take a look.

Creation of developer.buddypress.org (#6812) @tw2113 has set up test site at https://trexthepirate.com/buddypress/

Slack log: https://wordpress.slack.com/archives/buddypress/p1473274934000113

#3961, #5451, #6060, #6385, #6712, #6765, #6812, #6978, #7105, #7210, #7218, #7226, #7238, #7249, #dev-chat

Dev Chat Summary for August 31, 2016

BuddyPress 2.7

Trac Tickets

BP-legacy: split group single admin.php in separate template files (#7079) @hnla has committed this to trunk. If you have copied over `groups/single/admin.php` and made some changes, there won’t be any changes to your theme. You might want to consider, however, “updating your file/s to the newer modular markup to enjoy improvements”, @dcavins said.

Improve `$args` included in ⁠⁠⁠⁠`bp_current_user_can`⁠⁠⁠⁠ and ⁠⁠⁠⁠`bp_user_can`⁠⁠⁠⁠ filters (#7192) @dcavins requested feedback from @rayisme who gave the nod. Update: @dcavins has committed patch to trunk.

Select All link missing in BuddyPress Menu Selection (#5260) @tw2113 has committed patch to trunk.

Extract & relocate core markup functions: Theme compat include functionality & search forms file (#6844) @boonebgorges has committed this to trunk.

Use WP page names for BP directory pages headings (#6765) @hnla, @imath, @boonebgorges, and @dcavins have contributed patches for this ticket and @rayisme has shared a code snippet. @hnla requested dev feedback.

strtotime() is evil don’t use it (#5781) @rayisme has committed patches for this ticket. He requests feedback on the `5781.mysql2date.patch`. “All of our `⁠⁠⁠⁠strtotime()⁠⁠⁠⁠` calls assume that GMT is the default timezone.  If the server’s timezone is anything but GMT, then our time rendering is wrong. Almost all of BP’s timestamps are in GMT.” Dev feedback requested.

Screen notifications settings page (#6712) @rayisme has patch. Dev feedback welcome.

Date xprofile field enhancement (#5500) @boonebgorges has updated patch. This ticket “is mostly done – just working out a couple of UI and acccessibilty issues near the end.”

BP Types UI

@boonebgorges and @dcavins will be developing the new dashboard UI for creating Member Types and Group Types as a plugin first. @boonebgorges has created the new repo at https://github.com/buddypress/bp-types-ui

Slack log: https://wordpress.slack.com/archives/buddypress/p1472669906000142

#5260, #5500, #5781, #6712, #6765, #6844, #7079, #7192, #dev-chat