Write best practices and style guide #904
Conversation
EmilyGraceSeville7cf
force-pushed
the
feature/add-best-practices
branch
from
db74c9e
to
ecfb91c
Compare
|
I think it's interesting to write style guide for Nushell which we can later use to develop an autoformatter, but I think this text is written too authoritatively. The "Always do this and that..." formulations leave a hostile impression on the reader. I would formulate it not as a canonical style guide that you must follow but instead as a working document collecting style recommendations. It is going to evolve as Nushell evolves, we might reach different consensus on some issues etc. Also not sure if it should be book or somewhere else (maybe cookbook?). Nevertheless, I think it's a great first step towards having a style guide, once it is formulated a bit softer. Thanks! |
I've changed them to It's recommended to. :) |
EmilyGraceSeville7cf
force-pushed
the
feature/add-best-practices
branch
2 times, most recently
from
b0ac23f
to
8980677
Compare
|
@EmilySeville7cfg I'm not trying to be contentious. Thanks for putting this together. I'm betting there will be lots of opinions on what people like. It's a great conversation starter and think it's a great idea to have something like this, especially as it relates to creating a formatting tool. |
Co-authored-by: Darren Schroeder <[email protected]>
|
Any updates? :) |
|
i think we can merge this 👍 @fdncred |
|
I'm not signing off that all the styles documented here are what we want to move forward with, especially since I doubt JT and others have even looked at this PR. However, I think we could probably land it, point other core-team members to this link, and continue working on it. |
|
yup agree 👍 the idea was to avoid letting this PR die / live too long 😌 |
|
I am here again. ;) I see this PR is referenced in nushell/nufmt#11. Any extra updates about my style guide? |
|
Hey @EmilySeville7cfg! Welcome back. Hope you had a good trip and are ready to jump back in. I was just about to land this when I realized that I think it'll be hidden. If we intend this to be a chapter in the book, we need to have a link to it like all the other chapters are linked. I think it would best fit under "Programming in Nu". If we can finish updating the contributor-book, maybe a better place is to have it there? We can move it later if we want to. |
Why not? :) |
It just takes someone updating all the chapters (except plugins, which just got updated). If you want to do that, we can land this PR and then move it there when the contributor-book is finished? |
I want it. It's not clear for me now how exactly to update chapters. Refreshing code samples according to this style guide and checking whether everything is up to date? |
I think you just need to go to this link and update the markdown files. https://github.com/nushell/nushell.github.io/tree/main/contributor-book. I haven't looked at them in a while but the things that don't work in nushell anymore need to be updated. I think you understand that part. We'll have to take it chapter by chapter probably. |
|
Not sure if this is the correct place for it, I'll leave that up to the author/reviewers, but it would also be nice to add some style guides for contributing to the book. For example:
I'm sure other ideas can be added but these are just a few that I came across |
|
I think we should probably merge this. I'm not sure it's 100% right but it's more than we have. Related to @savente93's comment. We should have that too, but I'm not sure where. We should definitely make it clear how to contribute. |
|
I'll make a seperate issue for it then |
|
Let's move forward with this. If we end up not liking something, we can change it. |
closes #902