Sections of workflow to move to NMFS-wide guidance

kellijohnson-NOAA commented 3 months ago

Task for EVERYONE if you have an opinion

Below in individual comments, sections of the collaborative workflow will be listed that are being proposed for moving to some NMFS-level location where more people can have access to it. Please navigate to each comment and place a 👍 if you agree it should be moved and a 👎 if you think that it should stay where it is at.

Timeline

Voting will close in 2 weeks. So, please have your votes in by EOD on June 28th, 2024!

Background

Is your feature request related to a problem? Please describe. The collaborative workflow website is getting large, has medium costs regarding maintenance, and parts of it would be beneficial to more than just those NMFS employees in FIMS.

Describe the solution you'd like Some sections that provide NMFS-wide or larger guidance should be moved to a new location.

Describe alternatives you've considered

Leave the workflow as is and suggest that people point other NMFS employees to the NOAA-FIMS/collaborative_workflow.
Delete the collaborative workflow.

Neither of these were seen as viable alternatives during the FIMS seaside chat on this topic.

### Tasks
- [x] 06-developer-software-guide.Rmd
- [x] 07-contributor-guide.Rmd
- [x] 09-documentation-templates.Rmd
- [x] 10-testing.Rmd
- [x] 11-glossary.Rmd

kellijohnson-NOAA commented 3 months ago

Chapter 6 Developer Software Guide

6.01 git
6.0.2 Development environment
6.0.3 vscode setup
6.0.4 C++ compiler
6.0.5 GoogleTest
6.0.6 GDB debugger
6.0.7 Doxygen

This entire section would be moved and instead a list of needed software and a single link providing the location of where installation information can be found would be provided.

kellijohnson-NOAA commented 3 months ago

7.3 Coding Good Practices

kellijohnson-NOAA commented 3 months ago

7.5 GitHub Collaborative Environment

7.5.1 FIMS Branching Strategy
7.5.2 Branch Protection
7.5.3 GitHub cloning and branching
7.5.4 Outside collaborators and forks

kellijohnson-NOAA commented 3 months ago

7.7 Reporting Bugs

7.7.0.1 Before Submitting A Bug Report
7.7.0.2 How Do I Submit A (Good) Bug Report?

kellijohnson-NOAA commented 3 months ago

7.8 Suggesting Features

7.8.0.1 Before Submitting A Feature Suggestion
7.8.0.2 How Do I Submit A (Good) Feature Suggestion?
7.8.1 Issue Labels
7.8.2 Issue Templates

kellijohnson-NOAA commented 3 months ago

7.9 Branch Workflow

7.9.1 Branching Good Practices
7.9.2 Branch Naming Conventions
7.9.3 git workflow

kellijohnson-NOAA commented 3 months ago

7.11 Commit Messages

kellijohnson-NOAA commented 3 months ago

7.12 Merge Conflicts

7.12.1 What is a merge conflict?
7.12.2 How to prevent merge conflicts
7.12.3 How to resolve merge conflicts

kellijohnson-NOAA commented 3 months ago

7.13 Pull Requests

kellijohnson-NOAA commented 3 months ago

7.14 Code Review

7.14.1 Assigning Reviewers
7.14.2 Automated Testing
7.14.3 Review Checklist
7.14.4 Review Good Practices

kellijohnson-NOAA commented 3 months ago

7.15 Clean up local branches

kellijohnson-NOAA commented 3 months ago

7.16 GitHub Actions

7.16.1 Details on Backup Checks
7.16.2 Debugging Broken Runs
7.16.3 How do I request a new Github Action workflow?

kellijohnson-NOAA commented 3 months ago

Chapter 9 Documentation Template

9.1 Writing function reference
9.2 Writing a vignette
9.3 Step by step documentation update process

kellijohnson-NOAA commented 3 months ago

10.2 C++ unit testing and benchmarking

10.2.1 Requirements
10.2.2 Setup for Windows users
10.2.3 Adding cmake and ninja to your PATH on Windows
10.2.4 Setup for Linux and Mac users
10.2.5 How to edit your PATH and change file permissions for Linux and Mac
10.2.6 Set up FIMS testing project
10.2.7 Build and run the tests
10.2.8 Adding a C++ test
10.2.9 Add tests to tests/gtest/CMakeLists.txt and run a binary
10.2.10 Debugging a C++ test
10.2.11 Benchmark example
10.2.12 Add benchmarks to tests/gtest/CMakeLists.txt and run the benchmark
10.2.13 Clean up after running C++ tests

kellijohnson-NOAA commented 3 months ago

10.3 Templates for GoogleTest testing

10.3.1 Unit test template
10.3.2 Benchmark template
10.3.3 tests/gtest/CMakeLists.txt template

kellijohnson-NOAA commented 3 months ago

10.4 R testing

10.4.1 Testing FIMS locally
10.4.2 Testing using gdbsource
10.4.3 R testthat naming conventions and file organization
10.4.4 R testthat template

kellijohnson-NOAA commented 3 months ago

10.5 Test case documentation template and examples

10.5.1 Test case documentation template
10.5.2 Test case documentation examples

kellijohnson-NOAA commented 3 months ago

Testing Glossary

kellijohnson-NOAA commented 3 months ago

C++ Glossary

iantaylor-NOAA commented 3 months ago

I just voted 👎 for most things. If a NMFS-level document gets created, and fleshing out that document to make it useful outside of FIMS leads to lots of redundancy with the FIMS site, then I would happily reconsider.

k-doering-NOAA commented 3 months ago

One idea for a NMFS-wide place to move info to is the FIT blog. The repo that is building the blog is here: https://github.com/noaa-fisheries-integrated-toolbox/resources.

Another idea for reducing maintenance is linking directly to GitHub documentation rather than explaining something in the collaborative workflow, when possible. I think we've started to do this more and more, but flipping through the collaborative workflow doc, it looks like there are locations where we could do this more often.

cmlegault commented 3 months ago

Similar to Ian, I down voted most things because I don't want this knowledge to be lost, especially when we get more turnover in the FIMS team. While there is lots of guidance out there regarding many of these topics, having the approach we are using described in a single place prevents confusion and allows newcomers to see the approach we are using, especially when there are multiple good approaches and we just need to pick one. Thanks Kelli for asking about this though, it is good to do these sort of checks to make sure we are not creating unnecessary work as part of FIMS.

kellijohnson-NOAA commented 1 week ago

Thank you everyone for your votes. It is super helpful to know what is being used and what is not looked at. I have since condensed some portions, referenced links where others have the exact same documentation, and reorganized 3 sections. So, I will leave this issue open as I continue to work through more sections but I consider 06, 09, and 10 currently complete with #156.

NOAA-FIMS / collaborative_workflow