Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add troubleshooting guide #875

Merged
merged 13 commits into from
Jan 15, 2020
Merged

Add troubleshooting guide #875

merged 13 commits into from
Jan 15, 2020

Conversation

pared
Copy link
Contributor

@pared pared commented Dec 18, 2019

Disregard the recommendations below if you use Edit on GitHub button to improve the docs in place.

❗ Please read the guidelines in the Contributing to the Documentation list if you make any substantial changes to the documentation or JS engine.

🐛 Please make sure to mention Fix #issue (if applicable) in the description of the PR. This enables GitHub to link the PR to the corresponding bug and close it automatically when PR is merged.

Thank you for the contribution - we'll try to review and merge it as soon as possible. 🙏

Fixes #871

@pared pared changed the title [WIP] pull: add 'too many open files error' solution [WIP] pull/push: add 'too many open files error' solution Dec 18, 2019
@shcheklein
Copy link
Member

@jorgeorpinel @pared let's create a user guide Troubleshooting section. I don't like this duplication and complication of the command reference. We can create a separate page per error, or for now a single page with expandable blocks or h2 segments.

@shcheklein

This comment has been minimized.

@jorgeorpinel
Copy link
Contributor

@shcheklein my initial #871 (comment) was

If it will fit in a single paragraph I recommend using existing docs, probably some of the command references. It can be repeated in a few ones wherever it's appropriate.

We have several of these repeated notes, paragraphs, sentences in different docs already, especially command references. It makes sense since there's overlap in functionality or implementation details in many places.

I don't think we need a Common problems section though, since there's only one and can't foresee having others in the immediate future. Maybe just add the paragraph in the bottom of the Description section? Starting with "A known issue..."

@shcheklein
Copy link
Member

If it will fit in a single paragraph

It looks like it does not, right? at least it'a big paragraph already :) And it would be an artificial constraint to try to keep error explanations like this very short.

also, this is an edge case, it's not that important to include it into description for all commands (3 places at least?)

We have several of these repeated notes, paragraphs, sentences in different docs already, especially command references.

they are usually small, there are not so many of them, and it might be a problem for some of them that they are repeated. And to my point above - they are usually general enough and highlight some important workflow (like installing S3 with DVC), they do not serve as an explanation of an error code.

I don't think we need a Common problems section though

I like Troubleshooting as the name, someone has used it already in some comment - it makes sense to me :)

can't foresee having others in the immediate future

I can easily add a few :)One of the most commons - what should I do when I get "DVC is busy" message. There will be more and more as we move forward and improve interface.

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Dec 18, 2019

let's create a user guide Troubleshooting section

To be clear, I'm not opposed to this. It's a good option, and just link from these command refs. BTW @pared please notice my other #871 (comment) in the issue:

Maybe also checkout since it can include pull. Consider adding the note in the remote index page too.

@shcheklein:

at least it'a big paragraph already

Indeed, it's a long one even, my shorter version. Would be nicer to split it in 2.

I like Troubleshooting as the name

Yes, I like it too. Or/and Known issues

@shcheklein
Copy link
Member

I would say: Known issues and Troubleshooting have different meaning to me. First is about actual existing bugs (and probably our GH issue tracker represents it really well, though it can be complimented with some docs if some issues are not going to be fixed ... ever). Second is about solving troubles - they are not necessarily issues to me.

@jorgeorpinel
Copy link
Contributor

Agree. This file descriptor thing to me sounds like an issue that could have a code solution to me. Not sure though.

@pared
Copy link
Contributor Author

pared commented Dec 19, 2019

Agree. This file descriptor thing to me sounds like an issue that could have a code solution to me. Not sure though.

@jorgeorpinel yes, it is solvable, and this change is taking some time because we were discussing it a lot with @efiop and @Suor. Some of the conclusions can be found at
iterative/dvc#2866 and
iterative/dvc#2473

The conclusion was that we want to preserve quite high default value of jobs, and don't want to introduce complicated logic to adjust (only default) jobs value on a single remote (s3). In the future we will probably fix it by retrying after this fail, but that will probably need reorganizing error handling, so it will be bigger than try: except OsError
iterative/dvc#2965

@pared
Copy link
Contributor Author

pared commented Dec 19, 2019

@jorgeorpinel @shcheklein I created Troubleshooting User guide section and included @jorgeorpinel suggestion.

@pared pared requested a review from jorgeorpinel December 19, 2019 14:36
@pared pared changed the title [WIP] pull/push: add 'too many open files error' solution Add troubleshooting guid Dec 19, 2019
@pared pared changed the title Add troubleshooting guid Add troubleshooting guide Dec 19, 2019
@pared pared force-pushed the 2473 branch 3 times, most recently from d4fcdbe to 350b2db Compare December 19, 2019 14:39
Copy link
Member

@shcheklein shcheklein left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few improvement requests.

You also need to update the sidebar.json file to make this section active. See the contributing guide - it should include the instruction, I believe. I would recommend running this locally to test it.

@jorgeorpinel
Copy link
Contributor

yes, it is solvable...

Thanks for all the context @pared! So, my point was that this may not be a "trouble" the way @shcheklein described it, but in fact a "known issue". I think you're confirming this?

@shcheklein
Copy link
Member

@jorgeorpinel @pared if agree on it to be a "known issue" then we don't need this doc - let's open ticket in the Github DVC repo with a description, workaround, ETA on solving, etc. I don't think we need document this things. To me the current solution is a first iteration, but a solution - thus I was thinking this documentation makes sense and should be part of the troubleshooting.

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Dec 19, 2019

if agree on it to be a "known issue" then we don't need this doc... I don't think we need extra documentation besides GitHub issue tracker for "known issues" and "known problems" (in a sense that they are actual design bugs, bugs and/or are going to be fixed)

To be or not to be! (A known issue) That is the question. I like the "regular workflow, you just hit bumps" argument but not sure it's accurate. I have to yield to you guys in the end to decide what this thing is. But I think Ivan is right that a fully described issue on GH would be enough for "known issues".

Maybe @efiop or @Suor (mentioned before) have comments on this?

@shcheklein
Copy link
Member

shcheklein commented Dec 19, 2019

regular workflow, you just hit bumps

k, to be more precise :) regular workflow, advanced scenario, setting up it properly. It can be considered somewhat similar to that "slow linking" message we have.

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Jan 10, 2020

Done @pared. See d2293b5 ^

p.s. I went for err.dvc.org/{hdr} -> dvc.org/doc/user-guide/troubleshooting#{hdr} BTW but feel fee to change it as needed.

server.js Outdated Show resolved Hide resolved
server.js Outdated Show resolved Hide resolved
server.js Outdated Show resolved Hide resolved
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-landing-2473-amnjganfpaic8 January 10, 2020 18:50 Inactive
@shcheklein shcheklein temporarily deployed to dvc-landing-2473-amnjganfpaic8 January 13, 2020 15:30 Inactive
@pared
Copy link
Contributor Author

pared commented Jan 13, 2020

@shcheklein @jorgeorpinel updated the address in docs, also the dvc PR, now it looks like that:
asciicast

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Jan 13, 2020

updated the address in docs...

Thanks @pared. There's just this one matter to decide definitely on, I think: #875 (review) please weight in if you can 🙂

UPDATE: And this one about 301 vs 302 response codes actually: #875 (review) ... ✔️

and refactor redirect code for consistency with existing ones
per iterative#875 (review)
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-landing-2473-amnjganfpaic8 January 14, 2020 23:22 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-landing-2473-amnjganfpaic8 January 15, 2020 01:15 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-landing-2473-amnjganfpaic8 January 15, 2020 01:33 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-landing-2473-amnjganfpaic8 January 15, 2020 01:40 Inactive
@jorgeorpinel
Copy link
Contributor

Shortened nav title to just "Troubleshooting"

See https://dvc-landing-2473-amnjganfpaic8.herokuapp.com/doc/user-guide/troubleshooting

Opened web: enable custom anchor id/href for troubleshooting guide? #922

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

sync: prepare troubleshooting guide for Too many open files error
4 participants