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

docs: Add Development and Releases sections to the documentation #11932

Merged
merged 11 commits into from
Oct 24, 2023

Conversation

stinodego
Copy link
Member

@stinodego stinodego commented Oct 22, 2023

Changes

  • Added a section "Development" with two subsections:
    • Contributing - for now I copied the CONTRIBUTING.md here, but we can extend this with subpages including things like preferred code style etc.
    • Versioning - includes our versioning scheme and I wrote down our policy on breaking changes. I think this is important for managing user expectations going into 1.0.0
  • Added a section "Releases" with two subsections:
    • Changelog - for now this points to our GitHub releases, but I intend to set up our CI to publish the changelog to our docs too.
    • Upgrade guide - this should include an upgrade guide for each breaking release.
  • Add config file for the Markdown Link Checker, as it somehow is tripped up by crates.io links

After this is released, I will update CONTRIBUTING.md to point to the contributing information in the docs.

@github-actions github-actions bot added documentation Improvements or additions to documentation python Related to Python Polars rust Related to Rust Polars labels Oct 22, 2023
@stinodego stinodego marked this pull request as ready for review October 22, 2023 13:21
@alexander-beedie
Copy link
Collaborator

alexander-beedie commented Oct 23, 2023

Some near-subatomic grammar tweaks/suggestions from me 🤣

Co-authored-by: Alexander Beedie <[email protected]>
@stinodego
Copy link
Member Author

Thanks Alex - helpful for a non-native speaker like me :)


!!! warning Rust users only

The Rust API for Polars is currently not considered stable.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we word this less drastically? Maybe that we are more certain about the lazy API, but that the internals may expect more breaking API changes. Also because it is harder to hide the API than it is in python.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, will change the wording here!

Copy link
Member Author

@stinodego stinodego Oct 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't really have to say anything about the stability of the API. We just need to mention that we don't deprecate things in Rust. I rewrote it to:

Breaking changes to the Rust API are not deprecated first, but will be listed in the changelog.
Supporting deprecated functionality would slow down development too much at this point in time.

@ritchie46
Copy link
Member

Alright. Good to go and good addition.

@stinodego stinodego merged commit a5e4cdf into main Oct 24, 2023
4 checks passed
@stinodego stinodego deleted the docs-policy branch October 24, 2023 11:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation python Related to Python Polars rust Related to Rust Polars
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants