search

mesh-adaptation / mesh-adaptation-docs

Documentation source for Animate, Goalie, and Movement
MIT License
1 stars 0 forks source link

Move developer docs to webpage? #24

Closed jwallwork23 closed 2 months ago

jwallwork23 commented 2 months ago

Following #11, there is a developer docs page on the wiki. Might it be better to host this on the website?

We considered doing this in the original PR but it's probably better to make the shift as a separate piece of work.

stephankramer commented 2 months ago

Finally got around reading the developer notes. Should have reacted on #11 perhaps but I'm too late for that. They all look very sensible and I agree with (almost?) all of it. One point I don't fully understand is:

Whenever you make a change, commit it with a message starting with #XX, where again XX is the Issue number. This will provide updates to the Issue on progress that has been made (in the next step). Note: to start a commit message with a # you will need to change the comment character used by Git. To do this (setting the character to &, say):git config --global core.commentChar &. Also note: formatting checks may cause your commits to fail on the first attempt - see below for details.

Do you literally mean start the short one-liner message with #XX ? That seems to be asking for trouble and potentially breaking people's workflow, as indeed any line starting with # by default is interpreted as a comment. Asking people to change their global git config just to work on our project is a bit much imho. I would much prefer the style you've been using up till recently (are still using?) with #XX in brackets at the end of the one liner.

Another thing I was going to ask about - that I don't necessarily have a very strong or informed opinion on - but I noticed you seem to prefer and recommend unittest over plain pytest style tests. I has the impression unittest were a bit on their way out with people finding it a bit too boiler-platey. Tbh I don't find pytest's fixtures all that intuitive either, but at least I know how to operate it, run a specific test+parameter choice from the command line etc.

As a general point, I think we should keep in mind that this is just going to be one of the many packages people are working with and on (this is definitely the case for me) and so in general I prefer staying close to established practices in the wider Firedrake community (even if I don't always agree 100% with it) also to minimize the cognitive load of different packages, and workflows.

Anyway, just my 2 cents. On the actual issue at hand: my feeling is that things like installation instructions and developer notes that you may need tweaking regularly, and don't need to be as polished, are easier to maintain as a wiki than needing to go through a PR for every single change. We can always revert as needed and I don't think we'll likely end up in an edit-war :-) In any case, I don't have strong opinion either way. If we do keep it as a wiki, we should add some clear links to the wiki on the web-page (e.g. have an Installation section with just a "For installation instructions see https://github.com/mesh-adaptation/mesh-adaptation-docs/wiki/Installation-Instructions")

Speaking of which would you mind giving me edit access to the wiki, as I noticed a typo in the installation instructions.

jwallwork23 commented 2 months ago

Do you literally mean start the short one-liner message with #XX ? That seems to be asking for trouble and potentially breaking people's workflow, as indeed any line starting with # by default is interpreted as a comment. Asking people to change their global git config just to work on our project is a bit much imho. I would much prefer the style you've been using up till recently (are still using?) with #XX in brackets at the end of the one liner.

Fair point. I usually put #XX at the start and then when we merge with squash the commit message ends with (#XX), indeed. I can reword this to recommend putting a #XX link somewhere in the commit message to keep things linked up, but not enforcing it.

Another thing I was going to ask about - that I don't necessarily have a very strong or informed opinion on - but I noticed you seem to prefer and recommend unittest over plain pytest style tests. I has the impression unittest were a bit on their way out with people finding it a bit too boiler-platey. Tbh I don't find pytest's fixtures all that intuitive either, but at least I know how to operate it, run a specific test+parameter choice from the command line etc.

Yeah, I've been moving towards putting all unit tests in the unittest framework, as the inheritance and setUp and tearDown methods enable actual test code to be very short. I agree that it's not perfect and would be open to considering alternatives.

As a general point, I think we should keep in mind that this is just going to be one of the many packages people are working with and on (this is definitely the case for me) and so in general I prefer staying close to established practices in the wider Firedrake community (even if I don't always agree 100% with it) also to minimize the cognitive load of different packages, and workflows.

Yeah, that's fair enough. These dev docs were intended to be about getting people started with code development, rather than enforcing rules. So I'll reword in that direction :)

Anyway, just my 2 cents. On the actual issue at hand: my feeling is that things like installation instructions and developer notes that you may need tweaking regularly, and don't need to be as polished, are easier to maintain as a wiki than needing to go through a PR for every single change. We can always revert as needed and I don't think we'll likely end up in an edit-war :-) In any case, I don't have strong opinion either way. If we do keep it as a wiki, we should add some clear links to the wiki on the web-page (e.g. have an Installation section with just a "For installation instructions see https://github.com/mesh-adaptation/mesh-adaptation-docs/wiki/Installation-Instructions")

Fair point! Let's leave them in the wiki for now.

Speaking of which would you mind giving me edit access to the wiki, as I noticed a typo in the installation instructions.

I've just sent you an invitation to join as maintainer.

ddundo commented 2 months ago

Yeah, I've been moving towards putting all unit tests in the unittest framework, as the inheritance and setUp and tearDown methods enable actual test code to be very short. I agree that it's not perfect and would be open to considering alternatives.

I may be missing something but this is possible in pytest too ( https://docs.pytest.org/en/latest/how-to/xunit_setup.html )

jwallwork23 commented 2 months ago

I may be missing something but this is possible in pytest too ( https://docs.pytest.org/en/latest/how-to/xunit_setup.html )

Fair enough! Okay, maybe I meant I like the object-oriented approach with unittest.