Skip to content

docs: improve CONTRIBUTING.md #618

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

Merged
merged 2 commits into from Mar 3, 2022
Merged

docs: improve CONTRIBUTING.md #618

merged 2 commits into from Mar 3, 2022

Conversation

ghost
Copy link

@ghost ghost commented Mar 3, 2022

Description of your changes

This PR is mostly a tidy up work for CONTRIBUING.md: typos and spelling, formatting, copy-paste mistakes.
Additionally, it adds the missing lerna-test entry in the global package.json because it's mentioned in the guide.

CONTRIBUING.md is one of the first docs the prospective contributors will read, so it's important to keep it in a good shape.

How to verify this change

Review the CONTRIBUTING.md guide.
Run npm run lerna-test:unit in the root directory of the repo.

Related issues, RFCs

#115

PR status

Is this ready for review?: YES
Is it a breaking change?: NO

Checklist

  • My changes meet the tenets criteria
  • I have performed a self-review of my own code
  • I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
  • I have made corresponding changes to the documentation
  • I have made corresponding changes to the examples
  • My changes generate no new warnings
  • The code coverage hasn't decreased
  • I have added tests that prove my change is effective and works
  • New and existing unit tests pass locally and in Github Actions
  • Any dependent changes have been merged and published in downstream module
  • The PR title follows the conventional commit semantics

Breaking change checklist

  • I have documented the migration process
  • I have added, implemented necessary warnings (if it can live side by side)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Copy link
Contributor

@dreamorosi dreamorosi left a comment

Choose a reason for hiding this comment

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

This is great, thank you for taking the time to go through the whole doc and improving it; I agree with you that it's one of the most important ones in the whole repo.

Left one single comment about the lerna-test:unit comment which I think can be removed altogether in favour of npm run lerna-test.


To run unit tests you can either use
To run unit tests, you can either use:

* npm task `lerna-test:unit` (`npm run lerna-test:unit`) in root folder to run them all
Copy link
Contributor

Choose a reason for hiding this comment

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

I think we can actually remove this from the doc: lerna-test that we have now will run the test script in the package.json of each package (example) with in turn is an alias for the unit group.

Copy link
Author

Choose a reason for hiding this comment

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

We could keep it for consistency (because the packages also contain both test and test:unit that are in fact the same thing). Otherwise, it might be misleading - why can I run both npm run test:unit and npm run test in the package but only npm run lerna-test in the root?

Copy link
Contributor

Choose a reason for hiding this comment

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

Ok, makes sense. My reasoning was simply to avoid confusion and leave only one but I see where you're coming from. I've already approved the PR, I'll leave the conversation open so that the next reviewer can chime in if they want.

@dreamorosi dreamorosi assigned ghost Mar 3, 2022
@dreamorosi dreamorosi added the documentation Improvements or additions to documentation label Mar 3, 2022
@dreamorosi dreamorosi added this to the production-ready-release milestone Mar 3, 2022
Copy link
Contributor

@ijemmy ijemmy left a comment

Choose a reason for hiding this comment

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

Thanks for this. Several small details make big difference.

@dreamorosi dreamorosi merged commit f8ad423 into aws-powertools:main Mar 3, 2022
@ghost ghost deleted the docs-contributing branch March 3, 2022 15:30
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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants