How to correctly publish an extension?

[pftnhr]

I've made a little feature, which I'd like to publish. After a while I had all folders publish.php wanted me to create and one appeal worked. After that I made some changes und ran the command again. The answer from my terminal is:

❯ php yellow.php publish yellow-headinglink
Publishing extension files 100%... done
Yellow publish: 1 extension, 0 errors

but nothing happened in the yellow-extensions folder. Even when I deleted the downloads folder, I wasn't notified that it was missing.

What am I doing wrong?

[pftnhr]

PHP 8.2.9 is installed and publish still doesn't work.

[schulle4u]

As long as you have configured Status: experimental in the installation settings your extension won't show up in the official repository. The publish command however should update the version number and publication date in your own repository.

Se also: Supported status values.

[schulle4u]

Only the files you have defined in the installation settings are inside the zip file. Screenshots and documentation files are generally not needed anywhere else, therefore they are left out.

[pftnhr]

Ok, I was not aware of that. What remains is the fact that the date in the extension.ini isn't updated.

[schulle4u]

The publication date will be updated when you raise the version number.

[pftnhr]

Ok, I'll a look on that. Thank you!

[annaesvensson]

The specific problem with the yellow-headinglink repository should have been solved by Steffen's answer. However the output of the publish command was really confusing in this case, you could also say it was completely wrong, it said that 1 extension was published despite the experimental status in the settings. As a rule of thumb we want to remove complexity from people's everyday lives and this doesn't strike me as particularly straightforward.

I would like to get more feedback about making extensions from developers and designers. Maybe the existing tools are still too confusing and the existing documentation doesn't give enough explanation for beginners. Someone mentioned that a point-by-point guide is missing. What are the problems you encountered during the making of extensions? Can you describe what was missing from your point of view? Do you think we should document one additional step what you can do between "making an extension" and "publishing an extension"?

Let us know what you think. Any comments are welcome.

[pftnhr]

I would definitely welcome a point-to-point guide! The shell script does tell you that you have to create a folder with the name of the extension and a folder called yellow-extensions, and it also tells you that you have to enter the output path in yellow-system.ini.

Personally, however, I originally assumed that the publish script would fetch the extension files from the respective folders and more or less write the extension.ini itself. This would, of course, make the procedure a lot easier, as you could then have an installation for each extension in which you can test it extensively without having to constantly copy files back and forth.

But perhaps I am wishing for simplicity, the realisation of which would drive complexity to unimaginable heights.

However, I also imagine a point-to-point manual to be very complex when I think of how my setup looks:

• Server: MAMP Pro with PHP 8.2
• Environment: macOS with PHP 8.2 (homebrew)

but maybe that's not so tragic, since the productive server of most people is usually a web hoster.

If you could explain how the publish extension works, i.e. which files and folders have to be available and where, that would certainly help some people.

[annaesvensson]

Now there's a new way of publishing extensions. The publish command will take your meta information and modify the file system/extensions/update-available.ini in the main repository. This is the central place where we store the update settings for available extensions. Previously extensions were stored in the repository datenstrom/yellow-extensions, but this will be no longer needed in favour of individual repositories. There are a few more things the publish command can do, but this is done more or less automatically to make your life easier, for example the publish command can extract version number and publication date from your source code.

Here's what you do if you want to publish a new version of your extension:

1. Increase the version number in your source code, for example const VERSION = "1.2.3".
2. Copy the source code into your local GitHub folder, for example /Users/anna/Documents/GitHub/yellow-stockholm/.
3. Run the publish command at the command line, for example php yellow.php publish yellow-stockholm.
4. Upload your changes to GitHub and create a pull request for the repository datenstrom/yellow.

Hope this is less complicated.

[pftnhr]

That certainly sounds like it. I'll report back as soon as I create or update another extension.

[annaesvensson]

How was the experience with the latest publish command?

[pftnhr]

I still have to make sure that I am in the right directory and that all paths are correct. In the extension.ini I also have to update the published date manually each time.

I wish there was a php yellow.php dev installation prompt, which would load the publish extension, create a directory for the things to be published and write the path to the yellow-system.ini. Then you would have everything you need with one installation.

[GiovanniSalmeri]

I drop a line just to say that I couldn't yet test the new publish command, but I appreciate very much that a simpler way of publishing has been developed! I will come back with my impressions as soon as possible 😊

[schulle4u]

For the curious, I've published my current local Yellow development environment. I am a Windows user, but perhaps this might help as an example to close the gap between developing and publishing an extension.

[pftnhr]

Wow Steffen, thank you so much for this! That already helps with the set-up. But a few question marks remain:

1. in which directory do you develop and test your extensions?
2. how do your extension files get into the directory /GitHub/yellow-name?

Maybe there are more questions but these are the ones that interest me the most.

Thank you in advance
Robert

[schulle4u]

This is easier than you think. When building a new extension I already use the yellow-name directory as project folder and once I'm ready to publish my code, I simply initialize a new GitHub repository in this folder. The testing part however is still a little less comfortable, I copy my files by hand over into a Yellow test installation running in my WSL. But since a successful Yellow setup only takes two commands this is an acceptable effort for me. You could even use the same Yellow setup for publishing to test your extensions, but I personally like to keep things clean and mostly use a separate installation for testing purposes.

[annaesvensson]

About developing and testing extensions in a local development environment. As Steffen wrote, you have to install PHP, GitHub Desktop and a copy of Datenstrom Yellow. That's the hard part. Once you have completed the installation steps, they differ slightly on Mac/Linux/Windows, the rest of the steps are comparatively easy. Open a terminal window. Go to your installation folder, where your copy of Datenstrom Yellow is. Type php yellow.php serve and you start the built-in web server. Some people prefer to use an Apache/Nginx web server, but this is an optional installation step, you do fine with the built-in web server. From here everything's just files and folders. You can use your favorite text editor and change everything in the file manager on your computer.

[annaesvensson]

Let us know if you're stuck with making and publishing an extension. I think good starting points are the contribution guidelines and the experimental extension for developers by Steffen. Most extensions start as experimental. If extensions become more stable and more popular over time, they can switch from Status: experimental to Status: available. If you want to talk about a specific problem, please don't hesitate, we rather want to hear the truth than socially accepted correctness. When making your first extension there might be some stumbling blocks in the way, an interactive chat with other people can be a great way to get back on track. Tell others about your extension and make an announcement.

Two ideas for the future. We could improve our automatisms, for example let the publish command verify more requirements at run time and give helpful error messages. We could add clarifications to the checklist of what we expect, for example make a formal specification of the coding standard rather than pointing to example implementations of the coding standard. Yesterday I watched CCC presentations by Joscha Bach about how humans and machines learn. I personally prefer a hands-on approach and learning-by-doing, but I now understand better why some people prefer to read documentation and build mental models in their brain before diving into coding. There's value in having both good technology and good documentation.