Add a CONTRIBUTING.rst to projects set up with PyScaffold

[FlorianWilhelm]

Describe your use-case

In general, it seems like a common practice to have a CONTRIBUTING.rst file in the root of each repo. This helps users to get started. Also Github's Settings -> Community Option checks for the presence of one.

Describe the solution you would like to see for your use-case

One could add a default CONTRIBUTING.RST and also reference this file from the Sphinx index. Github provides several examples and there are others on the net.

[abravalheri]

I have added a series of PRs to address this issue, by revamping PyScaffold's own CONTRIBUTING.rst (#468 and #471) and then using it as a reference to create a template for new projects (#470).

There were a few things that I was not 100% sure:

• In order to improve CONTRIBUTING.rst, I have created a dev-guide (Add a dev guide to docs, to help potential contributors (2nd step #376) #467), but it shares a lot of content with the extension documentation. The most correct solution in this situation would be changing the extension documentation to remove the repeated content and just refer using a link to the dev-guide. However, this solution might be confusing for extension creators (they don't need to know how PyScaffold internal architecture works). Moreover, if the core concepts are not in the same page as the extensions, readers might be inclined to skip them... The solution I found was to separate the repeated code (Split extensions.rst into re-usable files and add pipeline image (1st step #376) #466) and use a include statement in sphinx to avoid double bookkeeping and inconsistency. This might not be ideal
• The proposed template depends on a series of choices from the package developer (e.g., where the code is being hosted, if they are using a public package index, etc). The way I worked around this issue was to add a series of TODO items to the template guiding the user to review it before compiling the docs (I also added a configuration to make Sphinx raise a warn for every TODO statement left in the docs).
• I tried to make the proposed template generic for open source and private projects, but I don't really know if it reads nicely for private projects...

Any suggestions/reviews are welcome.

[abravalheri]

@FlorianWilhelm I think we are all set here right?

If that is the case, I was planning to release v4.1...

So far, we have accumulated as new features/changes: a new linkcheck task in tox.ini, updated licenses (0BSD for generated code + new tamplate), better coveralls support from the Cirrus CI template, and the new CONTRIBUTING.

Should we wait a bit for something else? I think the #447 can wait another minor release...

[FlorianWilhelm]

Thanks, @abravalheri, yes, looks good. I was just wondering if we should first release ConfigUpdater 3.0 and then use it as a new dependency? Or should this better be than in a minor release?

[abravalheri]

I think any of the alternatives could do right? ConfigUpdater 3.0 was restructured, but it is still mostly backwards compatible, right?

We could release a beta for ConfigUpdater 3, just to have the chance to run PyScaffold's test suite and see if we need to fix anything...

[FlorianWilhelm]

Hi @abravalheri, I released a release candidate of ConfigUpdater 3.0 so we can try this.

[abravalheri]

Thank you very much @FlorianWilhelm.

I was a bit disconnected on holidays, I will try to get back to speed on all the topics we had open here and try to cover the missing steps soon 😝