Update contributing guide #2382

purva-thakre · 2024-05-23T14:44:49Z

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

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.

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

purva-thakre · 2024-05-23T14:55:30Z

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 · 2024-05-23T14:58:43Z

Codecov Report

All modified and coverable lines are covered by tests ✅

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

Additional details and impacted files

@@            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

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

natestemen

Nice updates! Looking good to me.

One question: 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!

CONTRIBUTING.md

docs/CONTRIBUTING_DOCS.md

purva-thakre · 2024-06-03T18:43:43Z

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 · 2024-06-03T19:42:24Z

Feel free to disregard my previous comment.

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

purva-thakre · 2024-06-04T21:39:32Z

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

mitiq/CONTRIBUTING.md

Line 8 in 837ea83

    
           3. opening a [discussion post](https://github.com/unitaryfund/mitiq/discussions) to ask a question (no stupid questions!), provide feedback, or show something off!

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

Spend some time writing a non-stupid question, or
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:

mitiq/docs/source/toc_contributing.md

Lines 1 to 8 in 837ea83

    
           # Contributing 
        
           ```{toctree} 
        
           --- 
        
           maxdepth: 2  
        
           --- 
        
           contributing.md 
        
           contributing_docs.md

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

natestemen · 2024-06-04T21:53:09Z

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 · 2024-06-05T14:46:54Z

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 · 2024-06-05T15:42:44Z

this PR is ready

natestemen

Thanks Purva! Looking good. Just some wordsmithing comments, nothing major.

CONTRIBUTING.md

natestemen · 2024-06-10T20:26:11Z

CONTRIBUTING.md

 ## Code of conduct
-Mitiq development abides to the [Contributors' Covenant](https://mitiq.readthedocs.io/en/latest/code_of_conduct.html).
+Mitiq development abides to the [](./code_of_conduct.md#contributor-covenant-code-of-conduct).


Unnecessary since the anchor is the title.

Suggested change

Mitiq development abides to the [](./code_of_conduct.md#contributor-covenant-code-of-conduct).

Mitiq development abides to the [](./code_of_conduct.md).

This was not working when I was checking the changes locally. The link was dead.

I had to make sure the main heading was specified after .md.

What error are you seeing? I just tried locally and it's working!

No error. The line appears as non-clickable as if we sandwiched the path of the md file in backticks.

If it works for you, I could give it a try and check it in the RTD build.

Looks good to me (same as what I see locally): https://mitiq--2382.org.readthedocs.build/en/2382/contributing.html#code-of-conduct

CONTRIBUTING.md

natestemen · 2024-06-10T20:33:02Z

docs/CONTRIBUTING_DOCS.md


 Information in the docs should be added as markdown files using the MyST markdown syntax.
-If you are adding a new file (as opposed to editing an existing one), ensure to add it to an associated TOC so that it is discoverable.
+If you are adding a new file (as opposed to editing an existing one), ensure to add it to an associated TOC so that it is discoverable. 


Suggested change

If you are adding a new file (as opposed to editing an existing one), ensure to add it to an associated TOC so that it is discoverable.

If you are adding a new file (as opposed to editing an existing one), ensure to add it to an associated TOC so that it is discoverable.

We should set up a linter for this.

If you use make docs without adding the new docs addition to the TOC, sphinx will complain that the file is not added anywhere. Do we still want to add a linter?

Sorry, I mean we should set up a linter to catch white space at the end of lines.

Ah. Will have to search for something.

I see there's a sphinx extension for it but a quick glance shows it is for .rst files only: https://github.com/sphinx-contrib/sphinx-lint

docs/CONTRIBUTING_DOCS.md

natestemen · 2024-06-10T20:37:15Z

docs/CONTRIBUTING_DOCS.md

-There is a [sample markdown formatted notebook in the `examples` directory](./examples/template.md) for you to take a look at as you write your own!
+There is a [sample markdown formatted notebook in the `examples` directory](../source/examples/template.md) for you to take a look at as you write your own!


I'm confused by this. It seems both main and this branch both work here. Any idea why that is? Is the path with source preferred?

Same as my other comment. I had to make sure I specified the full path. The link would not be live otherwise (locally).

I thin this is because CONTRIBUTING.md and CONTRIBUTING_DOCS.md files are in separate directories compared to the rest of the files in docs/

docs/CONTRIBUTING_DOCS.md

natestemen · 2024-06-10T20:39:40Z

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.

Co-authored-by: nate stemen <nate@unitary.fund>

* update both guides * forgot readme * move things around * inline link cleanup * Nate's review - corrected typos Co-authored-by: nate stemen <nate@unitary.fund> * Apply suggestions from code review Co-authored-by: nate stemen <nate@unitary.fund> --------- Co-authored-by: nate stemen <nate@unitary.fund>

purva-thakre added 2 commits May 23, 2024 09:44

update both guides

2e0eda7

forgot readme

357a71e

purva-thakre marked this pull request as ready for review May 23, 2024 14:52

natestemen reviewed May 24, 2024

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

docs/CONTRIBUTING_DOCS.md Show resolved Hide resolved

docs/CONTRIBUTING_DOCS.md Show resolved Hide resolved

cosenal requested a review from natestemen May 31, 2024 14:27

move things around

680f4b2

inline link cleanup

bae3ca8

natestemen approved these changes Jun 10, 2024

View reviewed changes

natestemen assigned purva-thakre Jun 10, 2024

natestemen added the documentation Improvements or additions to documentation label Jun 10, 2024

purva-thakre added this to the v0.38.0 milestone Jun 11, 2024

purva-thakre and others added 2 commits June 11, 2024 13:31

Nate's review - corrected typos

be836c8

Co-authored-by: nate stemen <nate@unitary.fund>

Apply suggestions from code review

c1b4cb6

Co-authored-by: nate stemen <nate@unitary.fund>

natestemen merged commit bf82e84 into main Jun 12, 2024
18 checks passed

natestemen deleted the update_contributing_guide branch June 12, 2024 14:28

purva-thakre mentioned this pull request Jun 12, 2024

Add a linter for docs/ #2407

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update contributing guide #2382

Update contributing guide #2382

purva-thakre commented May 23, 2024 •

edited

Loading

purva-thakre commented May 23, 2024

codecov bot commented May 23, 2024 •

edited

Loading

natestemen left a comment

purva-thakre commented Jun 3, 2024 •

edited

Loading

purva-thakre commented Jun 3, 2024

purva-thakre commented Jun 4, 2024 •

edited

Loading

natestemen commented Jun 4, 2024

purva-thakre commented Jun 5, 2024

purva-thakre commented Jun 5, 2024

natestemen left a comment

natestemen Jun 10, 2024

purva-thakre Jun 11, 2024

natestemen Jun 11, 2024

purva-thakre Jun 11, 2024

natestemen Jun 12, 2024

natestemen Jun 10, 2024

purva-thakre Jun 11, 2024 •

edited

Loading

natestemen Jun 11, 2024

purva-thakre Jun 11, 2024

natestemen Jun 10, 2024

purva-thakre Jun 11, 2024 •

edited

Loading

natestemen commented Jun 10, 2024

	Mitiq development abides to the [](./code_of_conduct.md#contributor-covenant-code-of-conduct).
	Mitiq development abides to the [](./code_of_conduct.md).

	If you are adding a new file (as opposed to editing an existing one), ensure to add it to an associated TOC so that it is discoverable.
	If you are adding a new file (as opposed to editing an existing one), ensure to add it to an associated TOC so that it is discoverable.

		There is a [sample markdown formatted notebook in the `examples` directory](./examples/template.md) for you to take a look at as you write your own!
		There is a [sample markdown formatted notebook in the `examples` directory](../source/examples/template.md) for you to take a look at as you write your own!

Update contributing guide #2382

Update contributing guide #2382

Conversation

purva-thakre commented May 23, 2024 • edited Loading

Description

License

purva-thakre commented May 23, 2024

codecov bot commented May 23, 2024 • edited Loading

Codecov Report

natestemen left a comment

Choose a reason for hiding this comment

purva-thakre commented Jun 3, 2024 • edited Loading

purva-thakre commented Jun 3, 2024

purva-thakre commented Jun 4, 2024 • edited Loading

natestemen commented Jun 4, 2024

purva-thakre commented Jun 5, 2024

purva-thakre commented Jun 5, 2024

natestemen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

purva-thakre Jun 11, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

purva-thakre Jun 11, 2024 • edited Loading

Choose a reason for hiding this comment

natestemen commented Jun 10, 2024

purva-thakre commented May 23, 2024 •

edited

Loading

codecov bot commented May 23, 2024 •

edited

Loading

purva-thakre commented Jun 3, 2024 •

edited

Loading

purva-thakre commented Jun 4, 2024 •

edited

Loading

purva-thakre Jun 11, 2024 •

edited

Loading

purva-thakre Jun 11, 2024 •

edited

Loading