[Deliverable] Nim C library guide

[gabrielmer]

Summary

As all projects in the IFT need to develop their own C libraries, Waku emerged as a reference in the matter for having the most developed and battle-tested library organization-wise.

Being the starting reference implementation for libraries, we need to create a guide so other projects can easily replicate our library design and create their own working libraries in a short time.

[fryorcraken]

Please clarify:

• where will this guide be added? I suggest to use an existing location instead of creating a new one. eg. https://status-im.github.io/nim-style-guide/language.result.html. We could even take this opportunity to move the guide to a better place. maybe logos-co? cc @Ivansete-status who pointed me to another nim guide recently

[gabrielmer]

Please clarify:

• where will this guide be added? I suggest to use an existing location instead of creating a new one. eg. https://status-im.github.io/nim-style-guide/language.result.html. We could even take this opportunity to move the guide to a better place. maybe logos-co? cc @Ivansete-status who pointed me to another nim guide recently

Good question! So we initially thought about having it in a repo instead of a website .
In my opinion, the most important assets will be templates that can be used as a reference which contain clear instructions on how to adapt them to create new libraries. And if we focus on such templates, I think the most comfortable place to have it is in a repo which can be cloned and then modified according to the instructions.

For example, here's how my v1 of of the template is looking: https://github.com/status-im/nim-c-library-guide/pull/1/files

There, I basically created a simple example of a working library which both covers and can be extended to many different technical cases. On top of each file that needs changes from the user, I added a comment with instructions on how to modify it in order to adapt them to a new library. I also added TODOs throughout the files with specific places where changes need to be made so it's even clearer.

We will later have to reorganize the repo to accommodate for docs and other templates (such as go-client implementation)

In any case, this is simply the initial version and the idea is to iterate from here, with both feedback and contributions with the guide's users. Happy to hear any recommendations and feedback on how to approach this task :)

[fryorcraken]

repo instead of a website .

Thanks to GitHub pages, a repo can be a website.

In anycase, I'd still recommend to refer to this repo from "somwhere".

For example, here's how my v1 of of the template is looking: status-im/nim-c-library-guide#1 (files)

Unsure status-im is the best org here. Would love some guidance from @corpetty

[fryorcraken]

Another question is that should it be better to finish the nwaku desktop milestone first, to ensure that the guidelines are "final" for all desktop OSes?

[gabrielmer]

Thanks to GitHub pages, a repo can be a website.

Doesn't GitHub pages turn a repo with markdown files into a website? or does it have a feature to present the repo's codebase in some nicer UI than the repo itself? The important thing of the example/guide is the code

In anycase, I'd still recommend to refer to this repo from "somwhere".

100%, there should be an entry point where the repo is referred to

Unsure status-im is the best org here. Would love some guidance from @corpetty

Makes sense! I chose status-im because is the org of most of the libraries and repos we use, but we can change it to Logos or some other org if preferred

[gabrielmer]

Another question is that should it be better to finish the nwaku desktop milestone first, to ensure that the guidelines are "final" for all desktop OSes?

I guess it depends on the priorities and preferences of the potential users, @corpetty and Iuri (can't tag) might have valuable input on it.

My personal opinion is that if it's a priority for other projects to build a library, then it's better for them to start working, testing and iterating on it now rather that waiting for it to be "final" for all OSes. Once we have it tested and supported on Windows, we'll have clear instructions on how to adapt it and the upgrade should be smooth and quick.

Note that I don't think that the design will be "final" anytime soon. The initial guide is just a draft on how to build what worked for us, but will probably go through many changes (both from bug fixes and optimizations we find ourselves, and from issues raised by other projects using it).

So at least initially, we will for sure need to use some kind of versioning of the template, and all projects creating libraries based on this template will have to upgrade regularly.
It should probably go through some kind of regular release process with clear instructions on how to upgrade. Don't want to add overhead though, so happy to hear about other alternatives :)

[fryorcraken]

Doesn't GitHub pages turn a repo with markdown files into a website? or does it have a feature to present the repo's codebase in some nicer UI than the repo itself?

You have to have "website code" in the repo, but like we do for docs.waku.org, we can have a framework that transform the MarkDown files from the repo into HTML.

We can get Comms Hubs help for that once we decide what to do.

At this point in time, I'd suggest adding it as a section in status-im.github.io/nim-style-guide/language.result.html. that can point to your templates.

[gabrielmer]

We could even take this opportunity to move the guide to a better place. maybe logos-co?

Tried to move the guide to the Logos org but I don't have the permissions:

I also have https://github.com/status-im/go-bindings-template in Status' org but I thought I was going to be able to change their orgs, so created the latest repo in Logos: https://github.com/logos-co/nim-library-template

All these repos will refer to each other and should be in the same org, so the damage is already done and we will need to change orgs or delete at least one of them 😶

Anyone with higher privileges that can do that? Maybe @jakubgs

[fryorcraken]

Tried to move the guide to the Logos org but I don't have the permissions:

You are not a maintainer of the status nim guide, so I would not try to move it without being a maintainer. Tersec is probably the owner.

But I would not worry about it for now, let's leave status nim where it is. IT could be a topic of discussion at a monthly nim meeting.

[gabrielmer]

You are not a maintainer of the status nim guide, so I would not try to move it without being a maintainer. Tersec is probably the owner.

I was referring to move the repos that I created (https://github.com/status-im/nim-c-library-guide, https://github.com/status-im/go-bindings-template) and have them under Logos.

The last template I created I did it under Logos (https://github.com/logos-co/nim-library-template) but now that I see that I can't move the others, then we're in a pretty inconsistent state.

Anyway, not urgent