workflow for documentation of issues #453
Replies: 0 comments 7 replies
-
|
This all makes sense to me. Thanks for spelling it all out. One addition piece of the workflow that is even more undeveloped is updating our test models. In theory, we could modify existing models or add new ones every time we add features or discover something that would benefit from additional testing. I've just added this issue nmfs-ost/ss3-test-models#46 based on the recently completed Pull Request. I'm sure there's a sweet spot in terms of how many models and how much testing is too little or too much, but right now I think we're erring on the side of not enough. |
Beta Was this translation helpful? Give feedback.
-
|
Which reminds me that for about 3 years I have been saying that I will finish a mega-test model. There at least is a branch that contains it. The idea being to manufacture a test case that contains lots of features and data types. |
Beta Was this translation helpful? Give feedback.
-
|
OK. I tried to create a new PR at first stage of the code development process, but it did not feel right. But I still want to end up with a concise description of the work that was done. If a future viewer goes to the change log and clicks on an issue, then are taken to the top of the stream of issue commentary. That argues for putting energy into assuring that when an issue is completed, the final story is concisely told at the top of the Issue chain, not in the PR. |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, I'm not a fan of PR-right away, either. I think the best solution is just to make sure the issue and PR are linked. Perhaps it is also possible to list the PR in the change log, also? I think this point also argues for a separate change log - if you have to edit the issue to add a concise description on the original issues (which seems confusing to me because I've never seen issues used like this) is it better to just create the change log entry? Just a thought, but I think it is up to the team. |
Beta Was this translation helpful? Give feedback.
-
|
agree on importance of that linkage
|
Beta Was this translation helpful? Give feedback.
-
|
I think that we should decrease the emphasis on the pull request for so many extra events. Instead, I think we can create a new template that takes away some of the auxiliary tasks that we are putting on the pull request. For example, we could use GitHub actions to open a new issue each time a pull request is merged that asks for information on what other repositories should be changed. That way if the pull request is linked to the issue, the subsequent issues that are opened from a merged pull request would also be linked to the issue. I think the pull request comments should be refocused to comment on the code changes that are included in the pull request and bring it more back to a review of the code. I have a few more thoughts on easy things that we could do to clean up this process but I need a bit more time to think them through. |
Beta Was this translation helpful? Give feedback.
-
|
I am experimenting with a new Issue approach here: #68 |
Beta Was this translation helpful? Give feedback.
-
The situation I am interested in improving is the discussion of an issue under development, the transition of that issue to a PR where further discussion happens, then lack of a consistent approach for documentation of the final solution. Much of what you see below is largely a "note to self" so I can improve my own discipline in using the system.
Here are the steps I see happening currently in my workflow:
step 1: create a new issue. Right now I am liking the templates with [bug], [feature] etc.
step 2: some discussion to clarify the issue, plus other random chatter. Labels may get assigned to the issue
step 3: create a branch for the issue.
step 4: start development
step 5: create a PR sometime in the development process, note that the PR cannot be created until after there has been some change to the code in the branch. The template asks for linkage to an issue and concise description, which is good. But other items in the template cannot be filled in until development is complete.
step 6: development continues and discussion about the development occurs. Info requested in the PR template accumulates in that discussion. r4ss development occurs in parallel because successful GHA depends on both working together for existing features, but not for the new feature under development.
step 7: completion. Labels get updated on the issue, with "resolved" and "change log" added if appropriate. Linkage between the originating issue and the PR gets double-checked. Automation of creation of issues for updates to r4ss, manual, SSI is a bit ragged still.
What could be improved:
a. revise PR template to make it clear which items get entered when the PR is created, and which items will be completed by editing in the template as the PR gets completed and merged. Code documentation entry should be more than a check box and should prompt for a concise description of the code modification that occurred. zip with example should be added at the end of the process.
b. The PR template contains the most complete description of what was done, but the change log links to the originating issue. That is OK, but makes it very important that the link between issue and PR is always there.
c. chatter about the development of the solution tends to be in the PR channel. That is OK, but final resolution needs to be summarized in the PR template at the top of that chain.
d. any checkboxes should be added by editing in the PR template, not added down in the discussion chain.
e. hard to know in the original PR whether or not the r4ss and doc changes have been made as the issues in those repos have no linkage to the originating PR. [check this]
I have edited a recent PR to try to follow the above: #410
Beta Was this translation helpful? Give feedback.
All reactions