New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add draft for the intro blog post on ci and linting #62

Closed

lauraporta wants to merge 2 commits into main from blog-post-2

Member

lauraporta commented Sep 22, 2023 •

edited

Loading

Description

What is this PR

Bug fix
Addition of a new feature
Other

Why is this PR needed?
Starting the blog post series on CI and linting.
This the intro article that uses cooking metaphors 🍪 to introduce basic concepts that will be explained in detail in further articles. Let me know if these make sense to you!

A more detailed blogpost on linting will follow.

What does this PR do?
Adds the .md file with the article and a related image.

References

From slack conversation:

write_blog("What is all the stuff the NIU keep going on about? CI? linting? What's a ruff, is it black?")

for topic in [code_autoformatting, CI, testing]:
    write_blog(f"Introduction to {topic} on abstract level")
    write_blog(f"How does NIU implement {topic} in practice")

How has this PR been tested?

Built locally, tested functionality of the website manually

Is this a breaking change?

No

Does this PR require an update to the documentation?

No

Checklist:

The code has been tested locally
Tests have been added to cover all new functionality
The documentation has been updated to reflect any changes
The code has been formatted with pre-commit


          Add draft for the intro blog post on ci and linting

e08bb77

lauraporta requested a review from adamltyson

September 22, 2023 11:25

adamltyson requested changes

View reviewed changes

Member

adamltyson left a comment

I like this approach, but I don't think it's particularly clear to the novices we're targeting. I may be wrong though. What are your thoughts @alessandrofelder, I think you've taught things like this before?

Maybe we should get feedback from other, non SWEs?

docs/source/_static/blog_images/intro_to_linting_and_ci/cookies.jpg Outdated

Member

adamltyson Sep 23, 2023

do we have a license for this image?

Member Author

lauraporta Oct 20, 2023

It's a photo from Unsplash, I have to reference the author

docs/source/blog/intro_to_linting_and_ci.md Outdated Show resolved Hide resolved

docs/source/blog/intro_to_linting_and_ci.md

+              Imagine baking a cake. If you don't taste-test as you go, you might end up with a salty dessert. Without CI, small errors in code can create big problems later.
+              ## What about linting?
+              Linting is like having a baking mentor who guides you on techniques, ensuring your cake rises perfectly every time. It points out potential issues in your recipe (code) so you can fix them before baking.

Member

adamltyson Sep 23, 2023

Is this metaphor correct? I would think that this is closer to testing. Although linters can check for mistakes, it's testing that we usually use to make sure the code works properly.

docs/source/blog/intro_to_linting_and_ci.md

+              ### How does linting work?
+              Linting is a process that checks your code for errors, bugs, and stylistic issues. It's like a **spell-checker** for code. Usually, you run it before committing your changes. It helps you maintain a consistent style and avoid errors, but differently from CI, it doesn't run your code.
+              ### What if I don't use linting?

Member

adamltyson Sep 23, 2023

I'm not 100% sure that this metaphor is helping. If you don't know anything about CI etc, I don't know that you would understand what the missing key ingredient is.

docs/source/blog/intro_to_linting_and_ci.md

+              Without linting, you might not notice that your cake recipe (code) is missing a key ingredient. Linting helps you spot errors before they cause problems.
+              ### How can I automate linting? Use pre-commit hooks
+              Pre-commit hooks are scripts that run before you commit your changes. They can be used to run linting automatically, so you don't have to remember to do it yourself. Tools like `black`, `mypy`, `ruff` can be called. They respectively check your code for style, type errors, and security issues.

Member

adamltyson Sep 23, 2023

Do people know what "commiting" is out of context? Also, I would introduce the tools in more detail rather than just mentioning their names.

We haven't explained what we mean by "style" or "type". Also, does ruff check for security issues?

docs/source/blog/intro_to_linting_and_ci.md

+              ### What is the difference between `ruff` and `black`?
+              `black` is a tool that checks your code for style issues. It's like a baking mentor who ensures your cake is always perfectly risen.
+              `ruff` is an extremely fast Python linter that like a Swiss army knife, can be used to check for style and type errors. It's like a 5-star Michelin chef who ensures your cake is perfectly risen, and that you didn't accidentally add salt instead of sugar.

Member

adamltyson Sep 23, 2023

Not sure I agree with the metaphor issue. Ruff mostly doesn't check that your cake works. It's still more about style. The difference (mostly, although this is changing) is that ruff identifies issues, and black fixes them.

Member

alessandrofelder commented Sep 25, 2023 •

edited

Loading

I think it's important to separate the what/why it's helpful/important (abstract concept) from the how (the actual tooling and implementation), which is done really well here.
I'm not sure CI and linting should be introduced together, but without testing? I would say we should introduce all three together, or all of them separately (I would be prefer separately?)?
I think examples are very helpful to explain things (to me at least).
while I am always very supportive of cooking analogies, I wonder whether it's confusing if we link to the diataxis framework in the documentation post (which also relies strongly on cooking analogies to explain stuff)? I do think if we find a good analogy/metaphor, that would be helpful. I like the spellchecker analogy for linting - that makes a lot of sense to me.


          Update docs/source/blog/intro_to_linting_and_ci.md

aed0582

Co-authored-by: Adam Tyson <[email protected]>

Member Author

lauraporta commented Oct 20, 2023

Thank you both for your feedback! 😀

It's hard to find the limit between maintaining the blog post short, simple and complete and at the same time avoid over simplification. I tried to do this by not getting into technical details and using a simple analogy, but it does not feel now that it works so well.

IMO it is important to stress why these topics (linting, testing and CI) require attention from the reader more than explaining technically how they work. If I manage to make them interested, they could then be pointed to more exhaustive explanations.

I think this needs to be an introductory simple blog post with all three. The three topics can be then discussed in detail somewhere else.

Regarding the diataxis framework, it looks to me that this blog post falls in the category of explanations. I can try to follow those rules.

lauraporta marked this pull request as draft

October 20, 2023 14:24

Member

adamltyson commented Oct 23, 2023

IMO it is important to stress why these topics (linting, testing and CI) require attention from the reader more than explaining technically how they work. If I manage to make them interested, they could then be pointed to more exhaustive explanations.
I think this needs to be an introductory simple blog post with all three. The three topics can be then discussed in detail somewhere else.

This sounds right to me. We can follow up later with further information.

Regarding the diataxis framework, it looks to me that this blog post falls in the category of explanations. I can try to follow those rules.

This is a blog post, not technically documentation, so I think you can write it however you like TBH.

Member

adamltyson commented Dec 11, 2023

@lauraporta is there much more to do on this? It would be cool to get it released.

Member

adamltyson commented Apr 30, 2024 •

edited

Loading

@lauraporta just bumping this, it's been open for 7 months! It can always be closed and reopened later.

Member Author

lauraporta commented May 1, 2024

Closing this PR for now, as I've not been working on it for a long time.

lauraporta closed this

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet