Documenting coding conventions for new comers.

[Jérémie Guichard]

Hi everybody,

It is not easy for new comers to know about conventions and best practices
to be followed when contributing to Subsurface. This creates overhead for
new comers and code maintainers.
New comers have to extensively browse the code to find utility functions
(or end up re-implement things that already exist), figure what should be
done where, etc... and often end up having to re-implement fixes since
original pull request do not follow Subsurface development common practices.
Code maintainers spend lot of time (re)explaining such practices while
doing code reviews.

To cope with this I've prepared a change introducing a new CONVENTIONS.md
file that is meant to collect such information:
https://github.com/Subsurface-divelog/subsurface/pull/1196 Any feedback is
welcome. Since it is the one convention I learned during a recent pull
request I proposed, I started with documenting the use of membuffer for
string manipulations...

I know that the majority of frequent contributors (that are the ones
knowing such conventions) do not have much free time to spend on describing
them. On my side I'm still pretty fresh with Subsurface development and do
not yet know much of them, but do currently have some free time to spend on
this topic. So feel free to post me a small note in this thread with some
of the conventions you know about, I'll happily prepare pull request with
detailed descriptions and examples.

While I'm talking about documentation for contributors, I have a question
regarding Subsurface website, more specifically the
https://subsurface-divelog.org/documentation/contributing/ page.
I've made a (already merged) change with a mention to the usage of
CHANGELOG.md https://github.com/Subsurface-divelog/subsurface/pull/1194
I have another one (to be reviewed) fixing few spelling mistakes:
https://github.com/Subsurface-divelog/subsurface/pull/1195
Then if/when the currently discussed pull request would be approved it
would be nice to reflect these changes in the corresponding page on
https://subsurface-divelog.org. The question is: Was this page manually
edited in Subsurface-website repository or was it actually generated from
markdown? If so, is the script available somewhere?

Wish you all a great day,

Jérémie
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.subsurface-divelog.org/pipermail/subsurface/attachments/20180409/740d7657/attachment.html>