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

Update contributing guide to be more friendly #837

Merged
merged 11 commits into from
Oct 4, 2024

Conversation

jhkennedy
Copy link
Collaborator

@jhkennedy jhkennedy commented Oct 3, 2024

earthaccess documentation currently states that creating an issue is required before submitting a PR, which I think is an unnecessary barrier to many possible contributions. For example, it makes little sense to require an issue to fix a documentation spelling error. More discussion in slack here: https://openscapes.slack.com/archives/C05TMK269HA/p1726880090555649

I've:

  • removed the " Ensure an issue exists representing the problem being solved in this PR." checklist item from our PR template
  • added a "thank you" as the first thing potential contributors see when coming the contributing docs
  • expanded the discussion of how to contribute
  • reworked the different PR paths to be tabs instead of sections
  • fixed a few typos
  • updated releasing.md to exclusively use MkDocs style admonitions so they render well in ReadTheDocs (it had a mix of GitHub style and MkDocs style, and the GitHub style ones don't render well in our docs website)
  • moved some of the documentation details to development.md to improve the flow
  • fixes Building documentation using nox #819 by adding a nox session for docs. Note:
    • mkdocs build does not have a --serve option as suggested in the issue so we need to use mkdocs serve
    • the --dirtyreload option to mkdocs serve has been renamed --dirty
    • I've removed scripts/docs-live.sh as it's been replaced by nox
    • I've also removed scripts/build-docs.sh as it appears to be unused and undocumented, but I did not add a nox session to build the docs since ReadTheDocs does that for us. It would be easy to add in however.
  • updated all documented usages of pip to be invoked in the preferred method python -m pip, except the discussion of pipx b/c there you actually don't want your environment python to be invoked and instead use your system one (in reality this should be discussed more and I think this difference makes it maybe not suitable for the quickstart, but I'm leaving it for now).
Pull Request (PR) draft checklist - click to expand
  • Please review our
    contributing documentation
    before getting started.
  • Ensure an issue exists representing the problem being solved in this PR. <- no.
  • Populate a descriptive title. For example, instead of "Updated README.md", use a
    title such as "Add testing details to the contributor section of the README".
    Example PRs: #763
  • Populate the body of the pull request with:
  • Update CHANGELOG.md with details about your change in a section titled
    ## Unreleased. If such a section does not exist, please create one. Follow
    Common Changelog for your additions.
    Example PRs: #763
  • Update the documentation and/or the README.md with details of changes to the
    earthaccess interface, if any. Consider new environment variables, function names,
    decorators, etc.

Click the "Ready for review" button at the bottom of the "Conversation" tab in GitHub
once these requirements are fulfilled. Don't worry if you see any test failures in
GitHub at this point!

Pull Request (PR) merge checklist - click to expand

Please do your best to complete these requirements! If you need help with any of these
requirements, you can ping the @nsidc/earthaccess-support team in a comment and we
will help you out!

  • Add unit tests for any new features.
  • Apply formatting and linting autofixes. You can add a GitHub comment in this Pull
    Request containing "pre-commit.ci autofix" to automate this.
  • Ensure all automated PR checks (seen at the bottom of the "conversation" tab) pass.
  • Get at least one approving review.

📚 Documentation preview 📚: https://earthaccess--837.org.readthedocs.build/en/837/

@codecov-commenter
Copy link

codecov-commenter commented Oct 3, 2024

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 73.85%. Comparing base (2f49c08) to head (93b59e8).
Report is 21 commits behind head on main.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #837      +/-   ##
==========================================
- Coverage   73.88%   73.85%   -0.04%     
==========================================
  Files          31       31              
  Lines        2003     2004       +1     
==========================================
  Hits         1480     1480              
- Misses        523      524       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@jhkennedy
Copy link
Collaborator Author

I expect we'll want to iterate quite a bit on language, but this should get the discussion going!

@jhkennedy jhkennedy marked this pull request as ready for review October 3, 2024 01:03
@jhkennedy jhkennedy requested review from mfisher87, chuckwondo and betolink and removed request for mfisher87 and chuckwondo October 3, 2024 01:03
@jhkennedy
Copy link
Collaborator Author

jhkennedy commented Oct 3, 2024

Oh, and for #819, I have not done this:

We'll need to add a section in the docs to clarify that integration tests and documentation will require that we export valid EDL credentials with certain EULAs approved.

Nor have I updated the CHANGELOG.md yet; figured we should settle on the PR and circle back to that.

mfisher87
mfisher87 previously approved these changes Oct 4, 2024
Copy link
Collaborator

@mfisher87 mfisher87 left a comment

Choose a reason for hiding this comment

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

Awesome work. I have some nitpicks! I don't feel the need to review again once they are addressed, but am happy to!

docs/contributing/development.md Outdated Show resolved Hide resolved
docs/contributing/development.md Outdated Show resolved Hide resolved
docs/contributing/development.md Show resolved Hide resolved
docs/contributing/development.md Outdated Show resolved Hide resolved
docs/contributing/development.md Show resolved Hide resolved
docs/contributing/index.md Outdated Show resolved Hide resolved
docs/contributing/index.md Outdated Show resolved Hide resolved
docs/contributing/index.md Outdated Show resolved Hide resolved
docs/contributing/index.md Outdated Show resolved Hide resolved
@@ -120,6 +120,8 @@ markdown_extensions:
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
Copy link
Collaborator

Choose a reason for hiding this comment

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

This option enables the content tabs alternate style, which has better behavior on mobile viewports, and is the only supported style

Then why isn't it the default 😆

Copy link
Collaborator Author

@jhkennedy jhkennedy Oct 4, 2024

Choose a reason for hiding this comment

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

¯\_(ツ)_/¯

docs/contributing/index.md Outdated Show resolved Hide resolved
@jhkennedy jhkennedy requested a review from mfisher87 October 4, 2024 14:06
mfisher87
mfisher87 previously approved these changes Oct 4, 2024
Copy link
Collaborator

@mfisher87 mfisher87 left a comment

Choose a reason for hiding this comment

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

🚀

docs/contributing/index.md Outdated Show resolved Hide resolved
Copy link

github-actions bot commented Oct 4, 2024

Binder 👈 Launch a binder notebook on this branch for commit 93b59e8

I will automatically update this comment whenever this PR is modified

@jhkennedy jhkennedy merged commit ed3fb7b into nsidc:main Oct 4, 2024
13 checks passed
@jhkennedy jhkennedy deleted the issue-pr-guidance branch October 4, 2024 14:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Building documentation using nox
3 participants