Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a CONTRIBUTING.rst to projects set up with PyScaffold #376

Closed
FlorianWilhelm opened this issue Jan 4, 2021 · 7 comments
Closed

Add a CONTRIBUTING.rst to projects set up with PyScaffold #376

FlorianWilhelm opened this issue Jan 4, 2021 · 7 comments
Labels
enhancement New feature or request
Milestone

Comments

@FlorianWilhelm
Copy link
Member

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
Copy link
Collaborator

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
Copy link
Collaborator

abravalheri commented Aug 9, 2021

@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
Copy link
Member Author

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
Copy link
Collaborator

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
Copy link
Member Author

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

@abravalheri
Copy link
Collaborator

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 😝

@FlorianWilhelm
Copy link
Member Author

Good to have you back @abravalheri! I hope you had a great time in your vacation :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants