Add Contributing.md or notes in the readme about contributing

[dancingbug]

As I've written a couple PRs and issues now I've been wondering what the main contributors' preferences are with regard to contributions, since there's no specified place to ask.

Some questions:

• Should I submit PRs first?
• Should I open an issue for discussions related to certain things (like API or architecture changes), before spending time on a PR?
• Do the main contributors have a certain set of features/upcoming changes in mind? Like a detailed roadmap, but it could be short-term
• What usage scenarios should be supported?
• What reference documentation is the crate based on, if any?

We could mention something about the Github workflow (ie run cargo fmt and cargo test before submitting a PR) even if it seems like common sense. Users of Firebird are likely to be users of other programming languages (Java, C#, Pascal variants, Python, C++) so it could be good to give a little bit of guidance for people who are still getting familiar with Rust ecosystem specifics.

I also notice many contributors are from Brasil. I assume their native language is Portuguese. If it's preferred not to discuss anything about that, I understand. But if some contributors want to say 'find me on #rust-br!' or if there's specific kinds of contributions related to language that they would find helpful, I think that's also useful to say.

[fernandobatels]

As I've written a couple PRs and issues now I've been wondering what the main contributors' preferences are with regard to contributions, since there's no specified place to ask.

Fell free to ask in here, in the github issues. We also have a [telegran group], now there are only Brazilian members, so we use Portugese, but we can change to English without problems.

Should I submit PRs first?

If you have fixed some bugs, or made small improvements, I think you can open a PR directly.

Should I open an issue for discussions related to certain things (like API or architecture changes), before spending time on a PR?

Yes. API changes or large changes, need to be discussed first, because we need understand what is the propose with some examples and more.

Do the main contributors have a certain set of features/upcoming changes in mind? Like a detailed roadmap, but it could be short-term

No. We don't have a roadmap yet, because the users are only using in tests cases or exploring the Rust + Firebird. If you have a feature list, feel free to share here.

We are working for keep the crate more simple as possible. So, advanced API's are welcome, but with a separated crates.

What usage scenarios should be supported?

Users migrating old applications. I don't see anyone write a new e-commerce site using Rust + Firebird, but fixing some performance issues in their ERP yes.

Feel free to discord.

What reference documentation is the crate based on, if any?

I think not, I started the project think in the rusqlite crate and his doc, but today we are with our own style of API and doc.

We could mention something about the Github workflow (ie run cargo fmt and cargo test before submitting a PR) even if it seems like common sense. Users of Firebird are likely to be users of other programming languages (Java, C#, Pascal variants, Python, C++) so it could be good to give a little bit of guidance for people who are still getting familiar with Rust ecosystem specifics.

I agree with you.

I also notice many contributors are from Brasil. I assume their native language is Portuguese. If it's preferred not to discuss anything about that, I understand. But if some contributors want to say 'find me on #rust-br!' or if there's specific kinds of contributions related to language that they would find helpful, I think that's also useful to say.

Yes, today all 'official' contributors are from Brasil. I want translate all basic instruction for our language, but Rust don't have a good traction here yet.

Our 'sub-official' telegran group is the only Portuguese(language) place related to the lib today.

---

So, you have interest in make a contributing.md file? You can handle that?

[dancingbug]

Yes I can do that.

I want translate all basic instruction for our language, but Rust don't have a good traction here yet.

@fernandobatels Could you elaborate on what issues you are facing? Are you referring mainly to localization in rustdoc (and maybe testing utils)? Do you want to open a TODO issue? Maybe it's well known in the rust-br community already. But perhaps someone will come along, see the issue and say "hey I actually wrote a tool for this exact problem".

When I said 'reference documentation' I mean things like Protocol Messages Implementation in python Firebird source code explorer Firebird wire protocol documentation (all from #22)

@jairinhohw maybe you have some other comments about articles/source code you found most helpful? I think it's impressive that you implemented the wire protocol in rust so quickly. I imagine by now you have a very good understanding of the BLR and wire protocol. Is this something you'd be willing to try to explain or answer questions about a little bit to help potential contributors?

If you know about where best to look about fbclient implementation details that could also be helpful.

I will make a separate issue for documentation relating to specific aspects of internals (Edit: Here- #62)

[jairinhohw]

When I said 'reference documentation' I mean things like Protocol Messages Implementation in python Firebird source code explorer Firebird wire protocol documentation (all from #22)

@jairinhohw maybe you have some other comments about articles/source code you found most helpful? I think it's impressive that you implemented the wire protocol in rust so quickly. I imagine by now you have a very good understanding of the BLR and wire protocol. Is this something you'd be willing to try to explain or answer questions about a little bit to help potential contributors?

If you know about where best to look about fbclient implementation details that could also be helpful.

I will make a separate issue for documentation relating to specific aspects of internals

The resources I've linked in the #22 are about all i could find (did not link the jaybird source as i found the implementation in python easier to read), so quite a bit of what i implemented is things I'm not really sure of how it works because of the lack of documentation, but I've commented the code to document my understanding of the things.

I would be glad to answer any questions i can about the implementation and protocol.

I plan to rewrite it to make it easier to read and document a bit more in time, as it seems to be working better than i expected.

[fernandobatels]

Yes I can do that.

I want translate all basic instruction for our language, but Rust don't have a good traction here yet.

@fernandobatels Could you elaborate on what issues you are facing?

I'm not currently working on any issues. I'm busy with personal issues. Maybe next week I'll be able to work on the project again.

Are you referring mainly to localization in rustdoc (and maybe testing utils)?

Yes, the official docs and the README.md.

Do you want to open a TODO issue? Maybe it's well known in the rust-br community already. But perhaps someone will come along, see the issue and say "hey I actually wrote a tool for this exact problem".

When I start the localization work I will open a new issue.

I already share the lib in the Brazilian rust group a while ago, and in some Firebird groups. The people are coming in his own time.

[fernandobatels]

Fell free to ask in here, in the github issues. We also have a [telegran group], now there are only Brazilian members, so we use Portugese, but we can change to English without problems.

The link to our group: https://web.telegram.org/#/im?p=@rsfbclient