Add contributing naming convention page

mfisher87 commented 4 months ago

For example, in our docs, do directories and file names use hyphens or underscores as separators?

Sherwin-14 commented 3 weeks ago

@mfisher87 How can we approach this one?

mfisher87 commented 3 weeks ago

Good question. I think we should add a new page in the contributing section and start documenting some of the unwritten rules we're following now. E.g.:

For Python code, we're following PEP8 for naming conventions.
For Jupyter Notebooks, let's pick whether we use underscores or hyphens in their names, and write one down. I don't think it matters what we pick, we can use the PR as a place to decide as a team. I think the PR should be created as a draft and marked for discussion, perhaps with the "Feedback requested" label, until we've made all those decisions, and then reviewed.
For docs, similarly, let's just pick one. We have a mix of hyphens and underscores in directory names as well as markdown filenames.
What other things can we think of that have unwritten naming rules? Or things that currently have no rules and needs standardization?

I think this is one of those things where the PR doesn't need to be complete or comprehensive, it just needs to get discussion started. We can even merge it when it's incomplete -- the documentation page serves to record the decisions we've made thus far, and we can always update it for future decisions!

Sherwin-14 commented 2 weeks ago

Should I make a PR for this one? I am thinking of adding some rules and making a PR and then we can discuss whether these rules are the ones we need going forward

Sherwin-14 commented 2 weeks ago

Good question. I think we should add a new page in the contributing section and start documenting some of the unwritten rules we're following now. E.g.:
* For Python code, we're following PEP8 for naming conventions.

* For Jupyter Notebooks, let's pick whether we use underscores or hyphens in their names, and write one down. I don't think it matters what we pick, we can use the PR as a place to decide as a team. I think the PR should be created as a draft and marked for discussion, perhaps with the "Feedback requested" label, until we've made all those decisions, and then reviewed.

* For docs, similarly, let's just pick one. We have a mix of hyphens and underscores in directory names as well as markdown filenames.

* What other things can we think of that have unwritten naming rules? Or things that currently have no rules and needs standardization?
I think this is one of those things where the PR doesn't need to be complete or comprehensive, it just needs to get discussion started. We can even merge it when it's incomplete -- the documentation page serves to record the decisions we've made thus far, and we can always update it for future decisions!

Tests might need some written rules for naming convention as well. Currently, all of them use underscores, so I think we should proceed forward with underscores as the naming convention for them(for the time being). Also, files (in earthaccess ) at this point in time doesn't need naming conventions, but in future we might need naming conventions for them as well.

mfisher87 commented 2 weeks ago

Should I make a PR for this one? I am thinking of adding some rules and making a PR and then we can discuss whether these rules are the ones we need going forward

I think this sounds like a great approach! It's cool if this page is very short for now as well. Just having a place to put that information will make it more likely we'll record it :)

Sherwin-14 commented 2 weeks ago

Good question. I think we should add a new page in the contributing section and start documenting some of the unwritten rules we're following now. E.g.:
* For Python code, we're following PEP8 for naming conventions.

* For Jupyter Notebooks, let's pick whether we use underscores or hyphens in their names, and write one down. I don't think it matters what we pick, we can use the PR as a place to decide as a team. I think the PR should be created as a draft and marked for discussion, perhaps with the "Feedback requested" label, until we've made all those decisions, and then reviewed.

* For docs, similarly, let's just pick one. We have a mix of hyphens and underscores in directory names as well as markdown filenames.

* What other things can we think of that have unwritten naming rules? Or things that currently have no rules and needs standardization?
I think this is one of those things where the PR doesn't need to be complete or comprehensive, it just needs to get discussion started. We can even merge it when it's incomplete -- the documentation page serves to record the decisions we've made thus far, and we can always update it for future decisions!
Tests might need some written rules for naming convention as well. Currently, all of them use underscores, so I think we should proceed forward with underscores as the naming convention for them. Also, files (in earthaccess ) at this point in time doesn't need naming conventions, but in future we might need naming conventions for them as well.

@mfisher87 what do you think about this?

mfisher87 commented 2 weeks ago

Tests might need some written rules for naming convention as well.

For tests, I think we could name some specifics, e.g. "our tests always start with test_", and link to pytest documentation (https://docs.pytest.org/en/stable/explanation/goodpractices.html#conventions-for-python-test-discovery) for the stuff that isn't unique to our project. For example, the pytest docs say tests can also end with _test.py, but we don't do that, so that's one of the things we want to document.

Currently, all of them use underscores, so I think we should proceed forward with underscores as the naming convention for them

This is actually one of the PEP8 conventions, so it's covered (https://peps.python.org/pep-0008/#package-and-module-names) :)

I'm not sure I gave you all the info you need here. Anything I might be missing?

Sherwin-14 commented 2 weeks ago

I think you have given me all that is required for raising a PR :)

mfisher87 commented 2 weeks ago

Rad! Thanks, Sherwin :)

Sherwin-14 commented 2 weeks ago

Rad! Thanks, Sherwin :)

Rad? I had to google it literally. New word unlocked!

mfisher87 commented 2 weeks ago

Haha, sorry, I definitely use a lot of outdated US slang! :rofl:

nsidc / earthaccess

Add contributing naming convention page #532