This adds the ability to silence Source status messages and progress bars.
This is intended to be used with the publish "wait for available"
system, which causes sources to repeatedly update which ends up spamming
the terminal.
docs(contrib): Create a file overview in the nightly docs
This is a follow up to #11809.
On top of what was in the old contrib, I added links out for `.cargo/config.toml`. I'm assuming there are more files that would be worth indexing here but we can add those over time.
My focus was on linking to the high-detail documentation. In some cases, this meant increasing visibility to make rustdoc happy. In the registry case, `sources::registry` is a great document to link to so I instead dropped links that rustdoc couldn't handle as they were to details covered in the bigger document or can easily be derived from it.
The rest of the file docs will need to be handled in a different way as they are details for people implementing file system interactions.
Accurately show status when downgrading dependencies
### What does this PR try to resolve?
A few times now I've ran into issues where Cargo ends up downgrading a dependency in order to satisfy a pinned dependency somewhere in the dependency graph. Unfortunately this is not clear in the output of `cargo update`, which just shows all the changed dependencies as `Updating`.
References:
* #5702
* [Finding a pinned dependency edge](https://users.rust-lang.org/t/finding-a-pinned-dependency-edge/81157)
* https://github.com/tokio-rs/axum/issues/1814
### How should we test and review this PR?
This is a small change that tries to make dependency downgrades stand out more in the output of `cargo update`. I have not added any new tests since the existing tests seem to cover this functionality.
Some tests still fail, these refer to Git dependencies. I'm honestly not sure how to handle these, so I'd like to get some feedback on this before I fix those tests up. Git commits form a DAG, so one option is to see if the new commit is an ancestor of the old one (mark as "updating"), if the old commit is an ancestor of the new one (mark as "downgrading"), or neither (could be from parallel branches) we could compare based on timestamp in that case.
### To do
* Fix up tests for Git dependency updates
This is a follow up to #11809.
On top of what was in the old contrib, I added links out for
`.cargo/config.toml`. I'm assuming there are more files that would be
worth indexing here but we can add those over time.
My focus was on linking to the high-detail documentation. In some
cases, this meant increasing visibility to make rustdoc happy. In the
registry case, `sources::registry` is a great document to link to so I
instead dropped links that rustdoc couldn't handle as they were to
details covered in the bigger document or can easily be derived from it.
The rest of the file docs will need to be handled in a different way as
they are details for people implementing file system interactions.
docs(contrib): Move Design Principles earlier in the book
This is the framing by which all contributions should happen, so this should come first before getting into what is needed to know to implement a change and test it.
This is also prep for adding a new Implementations Practices section to pull out various tips spread through the Architecture section. See #11841
docs(contrib): Point compilation docs to doc comments
This is a follow up to #11809, merging the description of compilation with what is in the source code, leaving a breadcrumb for people who were used to going to the old page (for now). The new entry point for finding this is the doc comment in `lib.rs`
Like with #11809, this also meant increasing the visibility of a mod. This mod is mostly re-exported already, so this doesn't seem too bad. I pointed directly to the `job _queue` mod rather than `JobQueue` because the mod had more of an architecture discussion. For `drain_the_queue`, I also pointed at the mod because it talks about it and this avoided making `DrainState` and `drain_the_queue` `pub(crate)`.
This still leaves
- Files
- Part of this indexes the architecture based on files generated and should be in `lib.rs`
- Part of this is filesystem best practices and should be moved out of the architecture overview into some kind of Implementation Practices
- Package and Resolution
- Console Output. This also likely belongs in an Implementation section
- Likely stuff in the testing section
This is the framing by which all contributions should happen, so this
should come first before getting into what is needed to know to
implement a change and test it.
This is also prep for adding a new Implementations Practices section to
pull out various tips spread through the Architecture section. See #11841
`cargo install --git` multiple packages with binaries found hint
### What does this PR try to resolve?
The issues discussed in: https://github.com/rust-lang/cargo/issues/4830
namely this one:
> 4. a multiple packages with binaries found error should give users a hint about how to specify a single crate
I think improving the error message to provide a suggestion is a simple change that would help a lot of people when this happens, sorry if I'm out of line for just opening a PR here :)
### Before
cargo 1.68.0 (115f34552 2023-02-26)
### After
### Additional information
I added in a related test documenting existing behaviours
* multiple_examples_error: "multiple packages with examples found" (i.e. not "binaries")
I added these tests which aren't necessarily related to this PR, but could be considered if the behaviour were to change
* `multiple_binaries_deep_select_uses_package_name`: it uses the name, not the path. Is this a problem for crates with the same name?
* `multiple_binaries_in_selected_package_installs_all`: so `--bins` is implied when a package is specified?
* `multiple_binaries_in_selected_package_with_bin_option_installs_only_one`: demonstrates a use case where `--bin` and `[crate]` are both used
Disable flaky auth tests when `gitoxide` runs them
The proper fix is in https://github.com/Byron/gitoxide/releases/tag/gix-v0.41.0
which unfortunately can't be used as it also comes with the latest `tempfile` v3.4
which causes other issues when compiling on some platforms.
Thus we first disable the flaky tests, and re-enable them with the `gix` upgrade
which should be possible once `tempfile` doesn't hinder `cargo` on some platforms
anymore.
Related to https://github.com/rust-lang/cargo/issues/11821
This PR is supposed to be followed up by #11831 which re-enables the flaky tests and fixes them properly by upgrading `gix` which contains the fix.
The proper fix is in https://github.com/Byron/gitoxide/releases/tag/gix-v0.41.0
which unfortunately can't be used as it also comes with the latest `tempfile` v3.4
which causes other issues when compiling on some platforms.
Thus we first disable the flaky tests, and re-enable them with the `gix` upgrade
which should be possible once `tempfile` doesn't hinder `cargo` on some platforms
anymore.
Related to https://github.com/rust-lang/cargo/issues/11821
docs(contrib): Move overview to lib
### What does this PR try to resolve?
Goals
- Move docs closer to their use to make them more likely to be updated
- More exhaustively rely on intra-doc links to keep the links valid through refactorings
To do this, I am exploring moving contributing documentation to their relevant libraries and linking out to them instead.
### How should we test and review this PR?
Look at the PR a commit at a time
```console
cargo doc --open
cargo doc --allow-private-items --open
```
### Additional information
In moving the content over, I felt a lot of our current intro documentation was a bit verbose, so I tried to shrink it down so that adding more content would not make it overwhelming
Unfortunately, the intra-doc links seem to follow the same visibility
rule as using the API items, meaning that for `lib.rs` to link to a
`mod`, it has to have visibility of the `mod`, requiring some mods to be
made `pub(crate)` that previously weren't. I've gone ahead and done
this for now as the goal of this effort is for us to catch broken docs
through refactorings by using intra-doc links.
For now, the contrib docs page that was moved just links to the nightly
docs. Over time, all of this will just be collapsed into the
architecture page which will link out to the nightly docs.
