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 "Project best practices" page #1760

Open
wants to merge 10 commits into
base: main
Choose a base branch
from

Conversation

frankharkins
Copy link
Member

@frankharkins frankharkins commented Jul 25, 2024

Adds a new page on best practices for ecosystem projects.

Link to preview

Copy link
Collaborator

@Eric-Arellano Eric-Arellano left a comment

Choose a reason for hiding this comment

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

Great work!

docs/open-source/best-practices.mdx Outdated Show resolved Hide resolved
docs/open-source/best-practices.mdx Show resolved Hide resolved
conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project).

* **GitHub actions**

Copy link
Collaborator

@Eric-Arellano Eric-Arellano Aug 30, 2024

Choose a reason for hiding this comment

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

Suggested change
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.

Copy link
Member Author

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 Show resolved Hide resolved
docs/open-source/best-practices.mdx Outdated Show resolved Hide resolved
docs/open-source/best-practices.mdx Outdated Show resolved Hide resolved
docs/open-source/best-practices.mdx Show resolved Hide resolved
docs/open-source/best-practices.mdx Outdated Show resolved Hide resolved
Comment on lines 80 to 90
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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
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.

Copy link
Collaborator

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.

Copy link
Member Author

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.

docs/open-source/best-practices.mdx Outdated Show resolved Hide resolved
Co-authored-by: abbycross <across@us.ibm.com>
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
frankharkins and others added 2 commits October 10, 2024 11:13
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: No status
Development

Successfully merging this pull request may close these issues.

3 participants