Documentation

[binaryfire]

Hey JJJ,

My developer was wondering if you have any documentation to help implement this in our own plugins?

Cheers

[szepeviktor]

Meanwhile your developer can see the code in plugins listed in the readme https://github.com/berlindb/core/blob/master/README.md

[binaryfire]

Thanks @szepeviktor but it would take a fair bit of reverse engineering to work everything out. He'll probably prefer to keep using his existing custom tables implementation for now.

I think some basic developer documentation is essential if you'd like BerlinDB to be more widely adopted. We'd have been happy to use it and contribute pull requests if we had the necessary info to get started.

[Mte90]

duplicate of #7

[alexstandiford]

What does the process of documenting something like Berlin actually look like? Where should the documentation live? How should it be structured? How should we roll it out?

It's unlikely that the docs will be written in one gigantic push. This probably needs broken down into smaller pieces.

[JJJ]

Let's use the Wiki functionality here in GitHub for now: https://github.com/berlindb/core/wiki

(We can always create an external site later if we grow out of the Wiki approach.)

[alexstandiford]

To kickstart this process, I am going to create the home page of the Wiki. Thanks to some great insights and guidance from @DrewAPicture, I've determined that the best place to start is with a table of contents.

This will serve as a checklist of topics that should be covered in the documentation. As we collectively go through and flesh out the docs, we can link from the table of contents to the documentation page. This will allow us to flesh out the actual content as we go.

The list that I create is not intended to be absolute in any manner. I expect it will be changed as we go, but we need to start somewhere.

[slaFFik]

@alexstandiford Any progress with the home page of the Wiki?

[varunsridharan]

@JJJ @alexstandiford i think https://gitbook.com would be a great choice for docs

[varunsridharan]

@JJJ @alexstandiford here is a docs space from gitbook https://varunsridharan.gitbook.io/berlindb/

[alexstandiford]

I finally got around to putting together a fundamental table of contents for BerlinDB: https://github.com/berlindb/core/wiki

I know it's not much, but it's a start.

It would be very helpful if y'all would take a moment to look over the list, and offer anything else that you think should be discussed. Thanks in advance.

[ashleyfae]

Looks good - thanks @alexstandiford . Perhaps a section on database table upgrades? How to write them, formatting, etc.

[bosconian-dynamics]

Hello all 👋

It's going to take me some time to wrap my head around this project, but I am in love with the idea!

I would be happy to contribute to initial documentation efforts as well. However, I am wondering if the project might use some repo-based documentation solution instead of GitHub Wikis, as since GitHub Wikis can only be cloned locally but cannot merge PRs - that is, contributors cannot really work directly on the Wikis, relegating the efforts to the berlindb team alone.

Short of any dedicated tool, I think a simple /docs directory containing markdown files is an easy place to start (or even stay - Gutenberg still uses this approach for several handbooks).

Thanks for your amazing work 🙂

[alexstandiford]

Hello all 👋

It's going to take me some time to wrap my head around this project, but I am in love with the idea!

I would be happy to contribute to initial documentation efforts as well. However, I am wondering if the project might use some repo-based documentation solution instead of GitHub Wikis, as since GitHub Wikis can only be cloned locally but cannot merge PRs - that is, contributors cannot really work directly on the Wikis, relegating the efforts to the berlindb team alone.

Short of any dedicated tool, I think a simple /docs directory containing markdown files is an easy place to start (or even stay - Gutenberg still uses this approach for several handbooks).

Thanks for your amazing work 🙂

Hi! I think at least an example repository would be immensely helpful to those who haven't used this yet. I know BerlinDB's current docs reference a few repositories that use BerlinDB, but it would be nice if we had an example based off of a database schema everyone inherently understands.

[bosconian-dynamics]

@alexstandiford I will study up and take a stab at this. Admittedly databases and ORM are somewhat outside of my expertise - but I would like to become more proficient in these areas.

I think a plugin for the de-facto todo list seems like maybe the most barebones example, and a good place to begin. I would endeavor to add more complex and real-world examples as my comprehension improves.

I'm certainly open to any thoughts you might have on a good example schema.

[alexstandiford]

@alexstandiford I will study up and take a stab at this. Admittedly databases and ORM are somewhat outside of my expertise - but I would like to become more proficient in these areas.

This isn't a bad thing! You have perspective that others don't have, and that can lead to documentation that's more-helpful than what more-experienced people may write.

[alexstandiford]

I went ahead and made a very basic implementation of BerlinDB as a WordPress plugin. It's intended to give people a no-frills place to look at how BerlinDB works. Here's the repository.

[bosconian-dynamics]

That's awesome!!

I've similarly been building out a thought and an implementation of what's expressed in the code and implantation thus far, here.

But I've been running into various questions and thoughts herein - like I wonder why it's necessary to explicitly specify the table's verbatim SQL schema in a the set_schema` method when the related Schema implementation and associated tables already posses all of the relevant information to define the schema within MySQL themselves?

I'm not sure where it would be appropriate to ask these questions - I could, as issues, but I fear that they're not necessarily deserving of the status of an issue, and worry for my inability to comprehend the specifics.

It is very possible that I should wait a few years to understand this project. But I would very much like to become involved now. I'm just not sure where or how to direct my more specific questions... I can see how the library was used elsewhere, it is only often less clear why it was used that way... I can build out use-case examples.

But what I'm working on now all seems a little empty, and I can't quite tell you why built them that way - I am simply emulating EDD, quite directly.

I guess, whether the examples pan out to be a single repository managed by the organization or a repo list therein, I'm wondering where I should ask all of my questions. They are question which those users after me will face, and thus constitute an FAQ, perhaps - but where do I put them now?

[alexstandiford]

I wonder why it's necessary to explicitly specify the table's verbatim SQL schema in a the set_schema` method when the related Schema implementation and associated tables already posses all of the relevant information to define the schema within MySQL themselves?

I believe this is something we've talked about changing in the future. I've talked a little with @jjj about this as well but we haven't formally made an issue on GitHub to discuss. Perhaps now is a time to-do so?

I'm not sure where it would be appropriate to ask these questions - I could, as issues, but I fear that they're not necessarily deserving of the status of an issue, and worry for my inability to comprehend the specifics.

Don't sweat it! Any feedback is appreciated, welcome, and encouraged.

It is very possible that I should wait a few years to understand this project. But I would very much like to become involved now. I'm just not sure where or how to direct my more specific questions... I can see how the library was used elsewhere, it is only often less clear why it was used that way... I can build out use-case examples.

But what I'm working on now all seems a little empty, and I can't quite tell you why built them that way - I am simply emulating EDD, quite directly.

I guess, whether the examples pan out to be a single repository managed by the organization or a repo list therein, I'm wondering where I should ask all of my questions. They are question which those users after me will face, and thus constitute an FAQ, perhaps - but where do I put them now?

Actually, the perfect place for this sort-of thing is the discussions section of the repository. It's a place to discuss, and ask questions about BerlinDB. Things that aren't actually issues, necessarily, just discussion points.

[JJJ]

I wonder why it's necessary to explicitly specify the table's verbatim SQL schema in a the set_schema method when the related Schema implementation and associated tables already posses all of the relevant information to define the schema within MySQL themselves?

🧐 I really like that you've noticed this, because you've spotted a bit of unfinished'ness, that will eventually render this bit of internal duplication completely unnecessary.

See: https://github.com/berlindb/core/blob/f902fb33d7701a5fb3bfa48074059d54712cbd1d/src/Database/Column.php#L886

The idea here is to simply generate the CREATE string and schema via a foreach loop through all of the Columns. It's conceptually possible, but I never got around to finishing it.

[bosconian-dynamics]

I believe this is something we've talked about changing in the future

you've spotted a bit of unfinished'ness, that will eventually render this bit of internal duplication completely unnecessary.

Ahh, awesome! Reassuring to hear that I was looking at that in an appropriate light.

GitHub Discussions is perfect - I had forgotten that it existed :)

[Mte90]

I see that the wiki was created but it is empty https://github.com/berlindb/core/wiki so some information outside the examples can be helpful.

[Mte90]

I see that the code is very well documented so the first step instead of the wiki should be generate an HTML version with phpdoc or similar. It is something that require less effort compared to the wiki as we saw.

[Mte90]

So I am trying but it is not clear how to use the various Query type for Compare/Date/Meta. I see on https://github.com/awesomemotive/sugarcalendar-core/search?q=date_query some date_query usage but is not clear how works or what are the parameters. On https://github.com/berlindb/wordpress-example there isn't anything so I have no clue how that stuff works...

[Mte90]

So after digging a bit in the code I think that I achieve it:

array(
			'date_query'  => array(
				'column'    => 'day',
				'inclusive' => true,
				'after'     => strtotime( 'now' ),
			),
		)

Reading the code is not clear if a date_query can have multiple sub arrays with other stuff.

[Mte90]

Also looking on the code seems that there are special columns like created/modified but they are not documented. At same time is not clear how to pass the value for a datetime column as a string fix it to 1970 etc. Require a datetime object? I have no idea.

Edit: my guess looking at some comments that require a strtotime formatted string