-
Notifications
You must be signed in to change notification settings - Fork 86
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 "Project best practices" page #1760
base: main
Are you sure you want to change the base?
Conversation
…H/ecosystem-best-practices
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great work!
conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project). | ||
|
||
* **GitHub actions** | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Software projects benefit from using continuous integration (CI) and continuous deployment (CD): | |
* [Continuous integration](https://www.atlassian.com/continuous-delivery/continuous-integration): automating the integration of changes to your code, including through the use of automated tests to ensure your changes do not break the project. | |
* [Continuous deployment](https://www.ibm.com/topics/continuous-deployment): automation of your deployment/release process. Often, continuous deployment can be semi-automated, such as requiring a human to initiate the deployment. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's a good idea to name-drop CI/CD so users can read about it more, but given the target audience, I think it's better as a "further reading" link at the end of the paragraph. Added in a7d02c7.
docs/open-source/best-practices.mdx
Outdated
The simplest way to list your requirements is to put the Python version you're | ||
using in your `README` and include a | ||
[`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) | ||
file in your repository. However, this means you must manually identify your | ||
requirements and keep the file in sync. | ||
|
||
Tools such as [Poetry](https://python-poetry.org/) solve this problem by | ||
managing dependencies for you, which means they can keep track of everything | ||
you've installed. Installing a dependency through Poetry will add it to a | ||
"lock" file, which keeps track of the exact versions of each package you have | ||
installed. Users can use the lockfile to replicate your environment. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The simplest way to list your requirements is to put the Python version you're | |
using in your `README` and include a | |
[`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) | |
file in your repository. However, this means you must manually identify your | |
requirements and keep the file in sync. | |
Tools such as [Poetry](https://python-poetry.org/) solve this problem by | |
managing dependencies for you, which means they can keep track of everything | |
you've installed. Installing a dependency through Poetry will add it to a | |
"lock" file, which keeps track of the exact versions of each package you have | |
installed. Users can use the lockfile to replicate your environment. | |
Traditionally, many Python projects use a `requirements.txt` file to list the project's dependencies. | |
You may also see `requirements-dev.txt` to list dependencies only used for contributing to | |
the project, such as linters or test runners. This approach can be fine, but it has two issues: | |
1) no "lockfiles", and 2) you still need to set up metadata about your project. | |
Instead of the traditional requirements.txt approach, build tools such as [Poetry](https://python-poetry.org/) improve dependency management. Poetry also ensures that you properly set up metadata for your project, | |
such as which Python versions you support; this metadata is necessary to | |
[package your project](#package-your-project). | |
Installing a dependency through Poetry will add it to a "lockfile", | |
which keeps track of the exact versions of each package you have | |
installed. Lockfiles are crucial for | |
["supply chain security"](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security). | |
Lockfiles also ensure that your project will not break overnight due to new releases of dependencies | |
breaking your project; with a lockfile, your dependencies will only change when you intentionally upgrade. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Eric-Arellano Is it important to put "supply chain security" in quotes? I'd leave them off unless it's confusing otherwise.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've incorporated this into f6977d8. I've left out the security bit as most projects are run-once programs for a specific experiment.
Co-authored-by: abbycross <across@us.ibm.com> Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Adds a new page on best practices for ecosystem projects.
Link to preview