Guidelines for developers (two versions)

[vissarion]

There are guidelines in two places

• https://github.com/boostorg/geometry/wiki/Guidelines-for-Developers
• https://github.com/boostorg/geometry/blob/develop/doc/guidelines.qbk

the first seems up-to-date, is the second deprecated? Is it safe to remove it?

[mloskot]

Sorry, I can't remember which why we copied it to the wiki

[awulkiew]

It is not used in the docs:
https://github.com/boostorg/geometry/blob/develop/doc/geometry.qbk#L149
I think it's safe to remove it. @barendgehrels ?

[barendgehrels]

The .qbk file seems the right one - but I don't know why it's unused and the wiki contained another one (probably not a .qbk...)

[awulkiew]

AFAIS it was never used.

[vissarion]

This seems like a more general issue, i.e. a lot of sections are duplicate in the wiki and in the .qbk files such as "design rationale" and "guidelines for developers".

And yes wiki is in markdown no qbk

[awulkiew]

Guidelines are up to date at GitHub and the introduction is up to date in the documentation.

After Boost was moved from SVN to GitHub I created this wiki by copying the first sections of the documentation as a minimal introduction of the library. I can't remember when I updated it after that. I think that more important is what follows, i.e. tutorials and guidelines. I think that the contribution guidelines should be here at GitHub where the developers are and that the documentation is more for the users.

So I'm ok with removing guidelines from the documenation and removing the introduction from the wiki.

[vissarion]

Apart from introduction there are also Compilation, Design Rationale and Quick Start that I guess we prefer to keep the doc version and delete the wiki one. But then there are "talks" which is only on wiki.

"Contribution Tutorial" and "Guidelines for Developers" should be in wiki only I agree with @awulkiew. Maybe adding a link to readme would be a good idea since I do not know who is visiting the wiki of github.

What about "Generating and Improving Documentation"? Here the wiki version seems more up to date than the doc one.

[mloskot]

What do you think about following the https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors and creating CONTRIBUTING.md file, then there are two options:

1. Move all the guidelines from the Wiki into the CONTRIBUTING.md
2. Link to the guidelines on the Wiki from the CONTRIBUTING.md

IMHO, nowadays the CONTRIBUTING.md is an obvious file potential contributors (should) look for.

An example from GIL https://github.com/boostorg/gil/blob/develop/CONTRIBUTING.md

[awulkiew]

@vissarion Yes, I was thinking about other sections taken from the docs the same as of introduction.

As for the talks I have no preference. The content seems to be more suitable for the users than contributors which would mean that the docs are a better place. However these talks are hosted at a third party site which is youtube and if they are moved or disabled we wouldn't be able to update the list if it was in the docs. Plus the users are also at GitHub.

What about "Generating and Improving Documentation"? Here the wiki version seems more up to date than the doc one

AFAIR there is no such section in the docs. In any case for me it falls into the guidelines for contributors.

@mloskot I think our contribution guidelines (tutorial, gudelines and documentation tutorial) are too big to be placed in this one file. If we think that we should have CONTRIBUTING.md then I'd rather do this the other way around. Leave the tutorials in the wiki and place links in the CONTRIBUTING.md pointing to the wiki.

Btw, nowadays there is also CHANGELOG.md but we wouldn't keep it up to date with the release notes in the docs. Unless there was a way of generating QBK from markdown.

[mloskot]

@awulkiew Sure, then the CONTRIBUTING.md could gather links to the Wiki pages, etc.