Oxford Common File Layout

Guidelines for OCFL Projects

Table of Contents

Guidelines for OCFL-based Projects

When to create new vs. requesting to co-maintain

Within open-source communities, too often new projects are started with nearly similar functionality; this leads to confusion and inefficiency. The OCFL community ascribes to the philosophy of collaboration over competition. With that in mind, please consider the following guidelines or ideas before starting a new OCFL-based project:

These guidelines are meant to help foster the OCFL community and ensure that we build upon the work of each other.

What to include in a README file for a project

All OCFL-based Projects should have a README file. The following sections should be included in the README:

Communicating about your OCFL-based project

Below are some strategies you can employ to communicate about your project to the OCFL Community:

Finding new maintainers for your OCFL-based project

Below are some strategies you can employ to find new maintainers for your project:

Guidelines for OCFL Contributed Projects in the OCFL GitHub

Contributors are able to host OCFL-based projects within the OCFL GitHub. The benefits of hosting your project are:

How to include a contributed project in the OCFL GitHub

Below are the steps you take in order to host your OCFL-contributed project in the OCFL’s GitHub.

  1. Send an email to ocfl-editors@googlegroups.com requesting to add a contributed project to the OCFL GitHub. Include in the email a link to the existing repository which should have a README file, a permissive license governing the code (Apache2, MIT, etc), your GitHub username, and information about organizations that are using the project.
  2. The OCFL Editors will review your request and will respond back letting you know whether or not the repository can be included in the OCFL GitHub and any next steps.

Co-maintaining contributed projects

Everyone can submit issues or pull requests to any repository in the OCFL GitHub at any time. Co-maintainers are individuals who usually have the permissions necessary to merge pull requests, commit to the main branch, and thus change a project’s code. If a project is not being maintained, you may be able to become the maintainer.

Taking over unsupported contributed projects

If you have been working in the issues section of an OCFL-contributed project, and you find that your work is not being acknowledged by the owner, the maintainer, or co-maintainers, you may be interested in becoming the project’s owner, or being added as a co-maintainer/maintainer; doing so may advance the development of the project. You can also use the below process if you are a co-maintainer and you think it is more appropriate for you to become the project’s owner or maintainer.

  1. File an issue in the project’s issues section stating your interest in becoming the owner, maintainer, or co-maintainer. Give links to your work on the project demonstrating to others you are interested in improving and are actively involved in the project. Point out the motivation behind your request. (For example, you are already using the project and you want it to be well-maintained.)
  2. For the issue title, use “Offering to maintain [PROJECT_NAME]” or “Offering to co-maintain [PROJECT_NAME]”.
  3. Include a record of the attempts to make contact in the issue summary, spelling out who, when, and how. This information helps the OCFL Editors determine if they should act immediately or make their own attempts to contact the owners/maintainers/co-maintainers.
  4. If the owner replies and sets you up as a co-maintainer or maintainer, the issue is fixed.
  5. If the owner agrees to make you the new owner but cannot change the project owner, or the owner agrees to your request but doesn’t make any change, tag the OCFL Editors (@OCFL/editors) in the issue and let them know there is agreement but the owner is unable to make the change.
  6. If the owner privately agrees to transfer the ownership, ask for a comment on the issue you created.
  7. If the owner doesn’t reply after one month, tag the OCFL Editors (@OCFL/editors) letting them know there has been no movement for a month. The OCFL Editors will normally try to contact the owner as an extra safeguard. If the owner still doesn’t respond, the OCFL Editors will make a final decision about the request.
  8. A project that has been unmaintained for more than 6 months despite the efforts of the current maintainers and/or the Editors to identify a maintainer will be tagged as “Unmaintained”. The README will be updated to indicate this status and indicate that developers should avoid dependencies on the project. Nevertheless, such a project may still be revived through the process above.