New Release

[stpaultim]

(As a side note: The forked repository is 128 commits behind the main repository.)

@kiamlaluno - Do you mean that the dev branch is 128 commits behind the current release?

I know that there is still a lot of work to be done on this module. However, I expect some people are downloading this through the project installer and they are getting a version from 2017. Quite a bit of work has gone into this module.

Since this module is for educational use, I don't think there is a riks of releasing too often. We should just make sure to have a warning in the README that there is still much work to be done.

We could hold off a few more days, because I may make some improvements to the menu and page example modules. Or we could do a release immediately and then another if we get these other improvements done.

[stpaultim]

Current maintainers are:

Luke McCormick (https://github.com/cellear/)
Andy Shillingford (https://github.com/docwilmot/)
Alberto Paderno (https://github.com/kiamlaluno/)

So, @kiamlaluno - You could issue a release. ;-)

[stpaultim]

@kiamlaluno Are you comfortable merging PR's and/or cutting a new release?

@docwilmot Do you want to be involved?

[docwilmot]

@stpaultim @kiamlaluno since this module is sort of an "official" Backdrop module in contrib since it is parsed by API Module to appear in our API docs I would suggest maybe we get a core committer to have a say before we release? @jenlampton maybe?

[stpaultim]

@docwilmot This is interesting news. Maybe we should bring this up at a dev meeting to talk about best process for improving this module and to better understand how it is being used.

[avpaderno]

The API documentation pages do not require any release: They parse the code in the repository branch. That is why the code shown in ajax_example_progressbar_callback() uses tempstore_set() as per #103.

[avpaderno]

Given this is an example project, we do not need to create alpha or beta releases. I would create a new stable release once #105 is fixed.

[docwilmot]

I figured we were pulling from the repository, but I assumed someone in charge needed to press a button somewhere to sync things intermittently before they show in the API. Since our contrib repos are open to anyone to commit, that seems a bit loose.
In either case though, there's still value in getting some core committer oversight before an official release. Probably even more so if syncing changes are as unregulated as it seems.

[laryn]

Since our contrib repos are open to anyone to commit...

I think that was the case early on, but not for some time now (years I think) as contrib permissions beyond triage have tightened up to just maintainers + some teams.

[docwilmot]

"Anyone" was too broad; I mean other people who otherwise would not have authority to commit things to the core APIs. If its official API, it should be approved by official people, such as @laryn. 🙂

At least that is my thinking on the principle of the matter, may be wrong.

[laryn]

I get your point. I'm just worried that will slow things down here and I'd argue that the ability to edit documentation of an official API is different than actually having control of or changing the API itself.

[avpaderno]

The documentation comments used in this project's files do not change the core API. They just document the functions/classes/methods the project define, like any other project.
It just happens that this project's files are parsed too, but to make the code and its documentation easily accessible to everybody who is interested in understanding how to correctly use the Backdrop API.

I apologies if I was not clear in my previous comment: Every commit done in this project changes what shown in docs.backdropcms.org, limited to the documentation provided by this project (which cannot override what Backdrop core provides).

[docwilmot]

I'll be honest here: I did not realise that the Examples were being synced automatically to the docs after every commit. I'm not comfortable with a process that provides "official" examples without more collaboration than that.

I really want to be careful not to upset @kiamlaluno at all; we should be grateful for all the work thats been done, no question at here, and I hope this is understood and there are no hard feelings for these comments. But I just feel this needs group attention and consensus ideally from our core committers if these are to be truly representative official Examples.

I would be happier if this was mentioned at the Thursday meeting. Subsequently, I would also prefer if the Examples project was made the subject of some sort of group discussion or sprint to ensure we're all happy with the last many changes but at least a mention and an agreement at a Thursday meeting will do for me.

[avpaderno]

I am not upset at all, but I still have to understand what group consensus or attention is necessary for commits that, for example, change the code to use state_get()/state_set() or tempstore_get()/tempstore_set() for values that are not configuration values (and therefore do not need to be synchronized between development and production sites).

If the suggestion is to change how docs.backdropcms.org pulls changes from this repository, and pass from "pull the changes from the 1.x branch" to "pull the changes from latest created tag," I am fine with that, but I also wonder if that would just show to people who read docs.backdropcms.org code that is not updated and that does not yet correctly use the Backdrop core API. (For example, with few exceptions, the modules in this repository do not yet have a .json file for the default values for their configuration objects; most modules do not implement hook_config_info().)

[avpaderno]

Also, The modules in this project do not expose an official API; they use the official API, which is the Backdrop core API, which is not documented in the documentation comments this repository contain. Eventually, the comments in this repository suggests what Backdrop core API is better for a specific purpose; if those comments are not allowed, they should be all removed, starting from the ones that are not valid for Backdrop (since they have not been updated for Backdrop).

I am using the official API term in the same way Drupal uses the public API term, which does not include hook implementations, submission handlers, nor validation handlers. I apologize if I misunderstood, and Backdrop consider a specific hook implementation done by a module official API.

[avpaderno]

The only change I could propose is separating the documentation pages for this project from the documentation pages for Backdrop core; that is what api.drupal.org does.
Since both the sites use the API module, although (clearly) a Backdrop site uses the Backdrop port, what is achieved from a site can be achieved from the other site (as long as Composer is not required).