Update contributing guide

[purva-thakre]

Description

Updates the instructions for contributors in the documentation.

• Duplicated section Code of conduct was removed from contributing.md
• Wherever possible, internal html links were changed to .md links through cross-referencing
• A new QEM techniques checklist was added
• Another checklist for a new tutorial and/or user's guide was also added in contributing_docs.md.

---

License

• [x] I license this contribution under the terms of the GNU GPL, version 3 and grant Unitary Fund the right to provide additional permissions as described in section 7 of the GNU GPL, version 3.

Before opening the PR, please ensure you have completed the following where appropriate.

• [x] I added unit tests for new code.
• [x] I used type hints in function signatures.
• [x] I used Google-style docstrings for functions.
• [x] I updated the documentation where relevant.
• [x] Added myself / the copyright holder to the AUTHORS file

[purva-thakre]

Going to go ahead and mark this ready for review because the build passed locally with the newer changes.

@Misty-W @natestemen @nathanshammah I tried to think of all the things a person has to keep track of when adding a new method or a tutorial. Let me know if I forgot something!

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 98.31%. Comparing base (a0054fc) to head (c1b4cb6). Report is 12 commits behind head on main.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #2382 +/- ## ========================================== - Coverage 98.32% 98.31% -0.01% ========================================== Files 87 87 Lines 4059 4042 -17 ========================================== - Hits 3991 3974 -17 Misses 68 68 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[purva-thakre]

is it possible to use local links to markdown links instead of using mitiq.readthedocs.io links? I think it makes browsing the docs locally a little easier, and if it works then double win!

I am having some trouble with directly referencing .md files. Is there something I am doing incorrectly?

For example, in a line of Contributing.md, I want to link CONTRIBUTING_DOCS.md. I have tried a number of things and the build fails with myst.xref_missing error for all of them. In VS Code, when I use the correct link ./docs/CONTRIBUTING_DOCS.md or ./docs/CONTRIBUTING_DOCS.md#contributing-to-the-documentation, an option pops up to go to that link via CTRL + Click but make docs still gives me the error.

I have also tried using CONTRIBUTING_DOCS.md#contributing-to-the-documentation, CONTRIBUTING_DOCS.md (directly links the file), and #contributing-to-the-documentation (directly links the document title) in place of specifying the full path./docs/CONTRIBUTING_DOCS.md or ./docs/CONTRIBUTING_DOCS.md#contributing-to-the-documentation.

FWIW I have also verified I am using the correct heading anchors through myst-anchors CONTRIBUTING_DOCS.md in mitiq/docs/.

I could ignore these warnings through conf.py but the HTML build link for this reference does not work as well.

[purva-thakre]

Feel free to disregard my previous comment.

I should have used contributing_docs.md rather than CONTRIBUTING_DOCS.md.

[purva-thakre]

@natestemen I am thinking of replacing no stupid questions! part with the discussion FAQ's created by Jordan. WDYT?

https://github.com/unitaryfund/mitiq/blob/837ea83546f16e39867e3ee74cd27996b1d7509d/CONTRIBUTING.md?plain=1#L8

I feel the statement no stupid questions! is a bit ambiguous. Are we trying to say

1. Spend some time writing a non-stupid question, or
2. All questions are welcome. No need to think it's stupid.

Also, do you happen to know why the CONTRIBUTING.md file is in a separate directory compared to the other .md files in the docs? There's a similar issue with CONTRIBUTING_DOCS.md where it is not in docs/source. Both show up in the docs build due to below:

https://github.com/unitaryfund/mitiq/blob/837ea83546f16e39867e3ee74cd27996b1d7509d/docs/source/toc_contributing.md?plain=1#L1-L8

Then, what's the use of having docs/source/contributing_docs.md and docs/source/contributing.md as well?

[natestemen]

I feel the statement no stupid questions! is a bit ambiguous. Are we trying to say...

Definitely the latter. There are no stupid questions. Modifying it to make that point clearer is a good idea. Since the link is to the discussion page where the FAQ is pinned, I don't think we need to add an additional link here.

do you happen to know why the CONTRIBUTING.md file is in a separate directory compared to the other .md files

It's considered "best practice" by many to have a few things at the root of a repository. Usually you'll see a README, LICENSE, and CONTRIBUTING file, but some projects have more, such as a CoC, AUTHORS, CITATION, etc. I would guess this is the same or similar motivation as to why we have docs/CONTRIBUTING_DOCS.md, instead of putting the content in docs/source/contributing_docs.md.

what's the use of having docs/source/contributing_docs.md and docs/source/contributing.md as well?

Yeah so these files just exist to get CONTRIBUTING.md and docs/CONTRIBUTING_DOCS.md into the documentation build for the website.

[purva-thakre]

It's considered "best practice" by many to have a few things at the root of a repository.

That's pretty weird. readme and the docs build also allow access to these files anyway.

I found this stack overflow answer where the best practice of placing such files in the root of the repo has since changed to using .github, root of the repo or the docs folder.

https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file

[purva-thakre]

this PR is ready

[natestemen]

One general thing: make sure to have a PR description with... well a description of what the PR contains. Maybe some motivation/etc. This is especially helpful when looking back through the git history and trying to understand why things were changed.