Best practices

[cjgrady]

https://docs.python-guide.org/writing/structure/ has some good advice for best practices for a number of issues.

I think that the repository structure recommendations are particularly useful.

For docstrings, we have tried following the Google example and I think that works well. Additionally, it works with sphinx for user documentation. https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

I am still looking for CI recommendations. I have used travis a lot in the past but Lifemapper is still locked out as of 2021-03-25.

[cjgrady]

@maxpatiiuk @zzeppozz

[cjgrady]

PEP8
PEP20
are both good references.

[maxpatiiuk]

I am currently reading a book about Git. It has a great chapter about workflows for multiple contributors - https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows. It also has recommendations regarding commit messages.

Like @cjgrady said, having everyone fork the main repository and create topic branches seems to be the best practice for small teams.

Here is the full workflow:

• Fork a repository.
• Create a topic branch off upstream/develop (e.x origin/issue-53).
• Work on the topic branch.
• Before pushing, rebase it off upstream/develop just in case there were some commits in the meantime.
• Send a pull request to upstream/develop.
• Review the pull request and approve it.
• Delete the topic branch.
• If upstream/develop is tested and proven to be stable, merge it into upstream/master.
• Delete the forked repository.

See more

If you are working on several topic branches at the same time, you don't need to create a separate fork for each, but make sure to create topic branches off upstream/develop.

@cjgrady @zzeppozz Feel free to comment or add suggestions.

[cjgrady]

Thanks for the input Max.

I think that workflow could work but I would suggest changing it slightly to just sync your local fork rather than deleting it.

Let's try this out with lm_test and lmpy to see what we think.

[maxpatiiuk]

Section of the Pro Git book on GitHub - https://git-scm.com/book/en/v2/GitHub-Account-Setup-and-Configuration
It starts out with simple stuff but there are some useful things in there too

[maxpatiiuk]

Run this to rename default branch name to main:

git config --global init.defaultBranch main

[maxpatiiuk]

Also, what is your opinion on having long-running pull requests? For example, as soon as we create a topic branch, you create a pull-request for it. Then, additional pushes to the topic branches would update the pull request.

This would allow to easily see what everyone is working on on the topic branches. Additionally, it would run checks on the code (if we configure GitHub Actions to run on pull-requests).

Finally, pull-requests encourage asking questions and adding comments to the code.

Pull-requests that are not ready to be merged can contain [WIP] in their name (work in progress). Or, they can be marked as draft pull requests (GitHub has that feature when creating a new pull request)

Once it is ready to be merged/rebased, the pull request can be closed.

Here are some examples:
specify/specify7#792
lifemapper/lmtrex#22 (this pull request was closed prematurely, it's still a work in progress)

@cjgrady @zzeppozz are you okay with embracing this practice?

[maxpatiiuk]

GitHub's issues can have labels, milestones and projects. All of those things can be very helpful for keeping track of the things left to do and setting deadlines

Here is an example:
https://github.com/maxpatiiuk/TTS_King/issues

I would try creating an issue for each bug from now on. Also, adding some labels/milestones and projects can be useful.

[cjgrady]

I agree, this is the process that I use for lmpy and biotaphy. I think that it is good for setting a target for a release. I am putting one together for a version 1 of lm_test now.

I will say that it isn't always appropriate for more continuously updated projects but I think for any of the community tools we have been working on it is a good strategy.

I used this GitHub learning lab to establish practices for lmpy: Create a release based workflow

[cjgrady]

And then have milestones, for example, version 3.0.0 of lmpy (which needs to be reassessed but this is where it was at before my issues with travis.ci...) Lmpy 3.0 milestone