Create Developer Guide

[freemansw1]

We should create a developer/contributor guide. Black has a quite good one that we can model off of: https://black.readthedocs.io/en/stable/contributing/index.html

[JuliaKukulies]

Great, thanks for the example @freemansw1. I also like Satpy's developer guide as an additional inspiration.

Sections that I find relevant for contributing to tobac are for example:

• explain basic code structure and the responsibilities of the different submodules (so it becomes clear where in the code a certain feature needs to be added/modified)
• migrating to xarray and dask
• how to upload example data to zenodo
• writing unit tests

[JuliaKukulies]

As discussed in the developer meeting, @fsenf and me can have a more detailed look into that!

[JuliaKukulies]

Copying over from the workshop discussion:

• Discuss branching strategy
• Language around mentoring
• We will come alongside you and mentor you through the process
• Explicitly offer pair reviews
• Add in how git works
• Add in how to do a code review and expectations in code review
  • Include conventional comments?

From the meeting minutes, it is not clear if you had already agreed on a format of the developer guide. I would be in favor of simply making this a part of our RTD page. What do you think?

[freemansw1]

We did not agree on a format yet for the dev guide, and putting it in the RTD page makes a lot of sense.

Also should make sure to explicitly link to a code of conduct; probably the Python code of conduct?

[JuliaKukulies]

Also should make sure to explicitly link to a code of conduct; probably the Python code of conduct?

Yes, good point @freemansw1.

OK, so I could create a branch in my fork so we can start working on this collaboratively, @fsenf ?

[fsenf]

Hi @JuliaKukulies , sounds good! Please go ahead and start a branch in your fork. I will not be able to catch up until Friday, anyway ;-)

If we like to render our Code of Conduct under RTDs then we should place it under our docs folder. Otherwise we would need to adjust the sphinx configuration ...

Cheers

[JuliaKukulies]

Great, @fsenf. After a short discussion with @freemansw1, I have created an exp_* branch now rather than a branch in my fork: https://github.com/tobac-project/tobac/tree/exp_developer_guide. We should both be able to push commits to the branch, so we can work on the guide collaboratively without pull request reviews at that state and submit a pull request when we are ready.

Right, I think it is no problem to place the RTD pages for the code of conduct and the developer guide in tobac/doc/. I have started to add some subsection. Let me know what you think about the suggested structure, once you have a chance to look at that!

[lettlini]

I just had a look at the developer guide and I think it looks pretty good already!

Some resources I personally found extremely helpful are

• Google's Engineering Practices documentation: doing a code review can be very challenging if you are unfamiliar with the process. I think this set of documents provides a very good resource on how to get started.
• conventional: comments : Giving good, constructive feedback in code reviews is of key importance in our workflow. Using this standard as a guide is really helpful.
• Conventional Commits: another resource I found very helpful when it comes to writing meaningful commit messages.
• Draft Pull Requests: This makes it really easy to iteratively improve a PR with the feedback from others until the PR is ready for review.

Let me know what you think about including these resources in the developer guide.

[JuliaKukulies]

Thanks @lettlini, great suggestions! I had already included conventional comments, inspired by your very clear and structured code reviews :)

But will definitely include the other two as well and you can, of course, also push to this pull request draft if you come up with more things to add more or would like to change anything in the text!