Starting point for OCF projects
This section of the README should contain a brief description of the project. Perhaps give a short amount of context around why it exists; the problem it solves. By the end of reading this short paragraph, a contributor should not be confused as to the purpose of the repository and its role in the organisation.
They might even have an idea of how it could be useful to them!
Note
Any important callouts (informing visitors this repository is in early design stages, or not for general use, or requires a lot of prerequisite knowledge or infrastructure) should be placed in a note like this. Like: This repository does not hold template workflows, contributing guides, etc - head to OCF's .github repository for those.
How to install the project for general use (not for development), so:
"pip install x", or: "pull the latest checkpoint from y";
not: "clone the repo and run make install".
For example, to "install" this template as the basis of a new repository,
do the following:
- Click Use this template (in green) above the upper right of this file
- Select Create a new repository
- Create the new repository as desired
One or two short examples of using the project to solve a problem. Quick happy-path examples that show the project in action or outline a common use case.
Note
If the project does not have a clear usage pattern, consider informing the user as such in the first callout. Then you can skip Installation and Example usage - perhaps replacing them with a Quickstart section - or just moving straight on to Development.
Once you have installed the project into a new GitHub repository,
git clone it and cd into the created directory.
For a Python project:
- Modify the
pyproject.tomlfile, updating the name, description, authors, and dependencies as needed. - Update the name of the package from
ocf_templateto your package name. - Install the project in editable mode (in a new virtual environment!)
with
pip install -e ..
Also, importantly, update this README!
For other projects:
Simply delete src and pyproject.toml, and just use and update the README
part of the template as required.
When your project is up and running, add any relevant workflows from OCF's template workflows or otherwise. See Choosing and using a workflow template for more details.
For more information, head to the Documentation.
Link to the project's documentation, if it exists. Also consider internal linking to parts of interest of the documentation, such as Development, API, Configuration and so on.
Any major points from github discussions, or highlights from the documentation. If the same question is often asked, answer it in here!
Yes, this is an optional section.
No, that should be in example usage!
Like this! Questions in level three headings, answers in plain text.
Anything specific to getting set up for development on the project: required libraries, infrastructure, extra tools that may be desired (MyPy, pre-commit, etc). Also, how to run tests!
Make sure you have the most up to date drivers for your 32 GPU array to use this template!
Note
The development section might be contained within the documentation, in which case remove the Development section, and instead specify links to the relevant parts of the documentation in the Documentation section.
The couple of commands, and perhaps additional dependencies, to run the test suite of the application or service.
- PR's are welcome! See the Organisation Profile for details on contributing
- Find out about our other projects in the OCF Meta Repo
- Check out the OCF blog for updates
- Follow OCF on LinkedIn
Part of the Open Climate Fix community.
