While learning about eLxr from the online docs, I’ve been generating what I think are useful improvements and error corrections, I’ve pushed them to GitLab, tested them to validate, then submitted merge requests, but it doesn’t appear that any of my MRs have been approved/merged. I have MRs from over a week ago that correct simple and obvious errors that are still waiting for final approval.
This seems odd since the “Contribution Workflow” section for user documentation here:
openly invites interested developers to contribute to the improvement of the documentation as described in that section, so it’s discouraging to invest time to submit improvements if they simply sit there in the queue of MRs.
Am I doing something wrong? Is there some part of the submission protocol I’ve overlooked or done incorrectly?
Hi @rpjday - I’m the documentation maintainer and have reviewed your merge requests and responded to some of them. We require that two reviewers approve each request and have assigned yours. Please be patient with us as we’re preparing for a release this month.
While I have your attention, the method you are using to create MRs is causing a lot of extra work with our current workflow. I’m about to update our documentation contribution process, so since you’re involved now, I’m going to share it with you first.
I would like to ask you to do the following (going forward) in your contribution process:
Contact me be before creating a bunch of related MRs. I appreciate your involvement with the project, but if your goal is to help out, your approach is actually creating more work for the team.
Create an issue specific to the problem you’re trying to solve. For example, if you have MRs for application development, please create an issue concerning this and your intentions for resolving it. Doing so would have saved the time lost when you created an MR against a Debian release instead of eLxr.
Combine your recommendations specific to a workflow or procedure, instead of creating separate requests for each issue you find.
Thanks, and again, we really appreciate your help.
Hi, @markm. If you can tolerate another note, apologies for the way I’ve been submitting MRs, I have been ruined by the Yocto Project workflow of, “Slam a commit – no matter how trivial – up to the YP docs mailing list and let the docs maintainers take it from there.” So a couple questions to make sure I don’t waste any more of other peoples’ time. (For which I, as a Canadian, again apologize, because that’s what we do.)
First, must every MR be linked to an existing or newly-created issue? I’ve seen that instruction in some places but not others. And after I read that somewhere, when I submitted a MR, I looked for where I would identify the relevant issue but I saw nothing obvious. So is an issue mandatory for a MR and how would you identify it? It doesn’t seem like you are forced to supply one when submitting an MR.
As the the definition of an “issue,” how all-encompassing should it be and is it allowed to represent multiple MRs? Example issue: “Find all out-of-date references to ‘aria’ in ‘bianca’ documentation.” That’s a well-defined issue but I would not want to submit a single MR that tried to do all of that across the entire bianca docs. That would mean that one would still submit those MRs individually, even while all representing the same issue.
Finally, and occasionally, one runs across a blatant typo or mistake that deserves fixing in short order. Are short and quick MRs to resolve stuff like that still acceptable? And still require an issue?
To answer your question, yes, an issue is required. It’s already documented in our README and our Contributor’s guide, and is there for a reason.
It helps us start a dialog about your submission(s). As you may well know, GitLab can be pretty opaque in the fact that it just shows the current state of the source content, but not any plans for what’s going on in the content developer’s world, or their deliverables.
As for typos, we hate them, but they do happen. We prefer an issue be created, since it can be resolved quickly without the requiring the two approvals necessary for each MR.
Hope this helps answer your questions. I’ll be updating our README today with more clarification concerning this.