#4131 Write contributing guidelines in markup file and make them more visible in a project
Opened 5 months ago by jflory7. Modified 4 months ago

Summary

Put a text file with contributing guidelines in a specific path, boost visibility of guidelines across project

Background

Every project has a different way of doing things or has their own preferences. Documenting these things are helpful for new contributors. A project can write their own contributing guidelines in a Markdown file today, but it's on the maintainer to make them more visible and for the user to go and find them.

Making contributing guidelines more visible in the UI encourages maintainers to write them (because there is a higher chance they will be seen) and also reduces the burden on maintainers if they write good guidelines for new contributors to follow.

Details

I like GitHub's implementation. If you place a CONTRIBUTING.md file in the root directory or in a .github folder, this is a special path and the UI will offer suggestions in different places (e.g. filing a new issue or opening a pull request prompts you, "Did you already see the contributing guidelines?"). I would like to see something similar, except maybe a more platform-neutral vocabulary if I wanted to put it in a hidden directory.

Supporting UI for this is key. I think adding prompts in the following places is a good idea, if a project adds contributing guidelines:

  1. On Issues page
  2. On Pull Requests page
  3. When opening a new issue
  4. When opening a new PR

Outcome

  1. Easier for project maintainers to communicate their workflow / preferences to new contributors
  2. More likely a new contributor will actually notice the guidelines written

We already have something when opening new PRs: https://docs.pagure.org/pagure/usage/pr_custom_page.html
Adding something when opening new tickets could be interesting.

I'm not entirely sure about adding them on the issues or PRs pages to be honest, but maybe.

Question: is it problematic if that file isn't in the sources but rather in the requests or tickets git repo as we are doing so far?

Metadata Update from @pingou:
- Issue tagged with: RFE, UI

5 months ago

+1 and can be nice to have a CODE_OF CONDUCT.md

I'm not entirely sure about adding them on the issues or PRs pages to be honest, but maybe.

My motive for that is so guidelines are more visible and easily noticed, if a project maintainer takes the time to write them up.

Question: is it problematic if that file isn't in the sources but rather in the requests or tickets git repo as we are doing so far?

It's difficult to accept new pull requests for these repositories. I prefer to place them in the sources repo so they are visible and accessible for someone browsing through the project.

Login to comment on this ticket.

Metadata