[Request for Comments] Recommendations for FOSS Hack (and future) Partner Projects

These are a few recommendations for projects. This could be updated based on feedback and suggestions. Do add-on to this thread to propose.


If you are interested in becoming a Partner Project for FOSS Hack, and other future programs organized by FOSS United, we have the following expectations from you.

We have organized the expectations into different levels with Level 0 being the least we expect from your project and Level N as exceeding our expectations.

It includes suggestions to consider while curating issues as well, highlighted in level 1 and 2.

Level 0

  • A valid FOSS or OSI license.

    For example, MIT and BSD are popular licenses used by FOSS projects

  • An active Issue board.

    For example, if your project is hosted on GitHub, we recommend you create meaningful Issues

  • An active Discussion forum

    For example, if your project is hosted on GitHub, we recommend you to activate and set guidelines for “Discussions“

  • Bandwidth of Maintainers

    It is important for the maintainers to have time commitment to help onboard new contributors. In context of partner projects for FOSS Hack 2024, the expectations from maintainers are listed here.

  • For FOSSHack partner projects, it is encouraged to add a fosshack label to issues, to ensure easy visibility and filtering

    • Mentioning skills needed, programming languages, complexity of issues as tags are encouraged, since they are very helpful. It will help participants to zoom in on something of interest easily.

Level 1

  • Contributing guidelines.

    For example, create a Contributing.md that outlines the onboarding process for contributors

  • A Code of Conduct.

    The Code of Conduct sets the community standards; more than the community, it helps you (the project maintainers) ensure that you can drive the community in the direction you wish. See Your Code of Conduct | Open Source Guides for more information on why you need a Code of Conduct

    • Contributor Covenant is a good first place, adopted by popular OSS projects such as Linux, Bootstrap, TensorFlow, React, Kubernetes and more
    • Django Code of Conduct is another popular example to refer to when creating your Code of Conduct.
  • Issues that contain sufficient information to ensure that they can easily be picked up by potential contributors.

    For some projects, especially those with solo and part-time maintainers, the issues pertaining to our projects are stuck in our heads and not on an issue board. When potential contributors show up to our project and show interest in contributing, we shouldn’t be a bottleneck because we need to communicate the issues synchronously.

    The issues should contain sufficient information so that a skilled programmer can create a Pull Request without requiring any intervention from the Project maintainers.

    If some or all of the above are missing in your project, seek help from the community by opening issues for the same or by tagging issues that potential contributors could help by adding information to them.

Level 2

  • Setup and enforce coding standards for your project

    Most FOSS projects have adopted coding standards. For example, Ruff and Black are popular linting and formatting tools in the Python ecosystem, and Prettier is a similarly opinionated code formatter for web technologies like HTML, CSS, JS, and more.

    Projects have also adopted pre-commit hooks to ensure that code is validated before it gets checked into the Version Control System.

    If you haven’t done either or both, you should consider seeing if members of the community are interested in setting these up for your project.

  • Highlight low-hanging fruits

    Most OSS projects don’t get the kind of attention that a Django or a TensorFlow or a React get, which means that there should be many low-hanging issues that complete newcomers to the FOSS ecosystem should be able to work on. Trivial issues like improving docstrings, adding unit-tests and/or integration tests, improving/adding type hints to the codebase, etc are some such examples.

    Remember that complete newcomers have two barriers to overcome - the Project itself but also the Version Control System e.g. git and/or the web interface e.g. GitHub that we rely upon. The easier the project-specific task is, the more time the newcomers can take to become comfortable with Git and GitHub.

    Numerous trivial issues, if possible, can also be collated to make an issue of enough substance to attempt.

  • Documentation always comes last but it is one of the most important aspects of a FOSS project.

    This is an overtly reductive view but FOSS projects become popular because of two things - they solve meaningful problems and they communicate how their users can solve the problems using their projects effectively. This includes User Documentation, API documentation, Use Cases, Architecture Documentation, and more.

    Documentation cuts across skill levels i.e. newcomers can contribute minor improvements to existing documentation, skilled developers can work on auto generating the API documentation for your particular programming language, developers with prior project experience can create Architecture Documentation, etc.

    Overall, creating issues for what documentation your project needs ensures that non-code contributions can also flow into your project.

  • Contributions attributing to design can be considered too.

    If your project welcomes design contributions, they’re encouraged to be highlighted in the issues with a specific tag that gives them visibility.

    The use of contrib-design was proposed in the community before, and could be used to highlight these issues.

Level 3

Dig deep and create issues that involve large-scale refactoring and/or big feature additions

FOSS projects usually work on the implicit assumption that new contributors work on low-hanging fruit for a large amount of time, after which the project maintainers give them enough mentorship and insight to be able to work on a large-scale refactoring of the project and/or introduce big feature additions. (Note that in our experiences, big feature additions almost always involve refactoring, to some extent.) This does not have to be the case.

Skilled contributors who are looking for a weekend project that delivers significant value might be open to taking up a large-scale refactoring issue on a project that they are not at all familiar with. The refactoring might cause certain changes/additions in the codebase to become trivial whereas they were non-trivial earlier.

4 Likes

There are a number of interesting points on that post that might be valuable to new FOSS/COSS maintainers. An opinionated subset of what is mentioned in the post is

  • Create issue and pull request templates
  • Create issue forms instead of templates
  • Moderate issues and discussions
  • Create an editorconfig for consistent text editing
  • Set up pre-commit, pick out hooks, keep them updated
  • Chat, do you use Discord, Zulip, Matrix, IRC, a combination, a bridge?
  • Answer questions on GitHub discussions, chat, Stack Overflow
  • A website, release announcements, blog
  • Turning questions and answers into documentation improvements.
  • Documentation translations, keeping synchronized, finding and retaining translators
  • Documentation versions links to current stable version
  • Code of conduct baseline, moderation beyond that
  • Maintaining the ecosystem beyond the core libraries, community maintained projects
  • Template repository, make all projects use same layout, tools, and processes
  • Improve test coverage, organization, style
  • Improve PRs, rebase to retarget branch, squash work commits, fix changelog/docs style, add tests, etc.
  • Automate release process, document manual process
  • Keep up to date with Python changes, update tox/CI versions
  • Keep up to date with tool/dependency changes
  • License year is not needed/does not need to be updated
  • Deprecations, warnings, removals, messaging about pinning versions and testing
  • Supported versions policy, for bugs, for security, for Python, for dependencies
  • Collecting and listing resources
3 Likes

These points sound good to me. I think one thing that should definitely be mentioned is the time commitment for the maintainers; if they don’t have the time to onboard new contributors, it won’t help much being a partner project.

3 Likes

This is helpful!

Had mentioned it in a gist in the partner projects structure:

Will mention here too.