search

Esri / arcade-expressions

ArcGIS Arcade expression templates for all supported profiles in the ArcGIS platform.
Apache License 2.0
272 stars 95 forks source link

Add contributing guidelines #78

Closed hhkaos closed 11 months ago

hhkaos commented 11 months ago

After checking more carefully the repo, I have noticed given the lack of conventions, there is considerable heterogeneity in the repo. To help keeping the repo in a good shape, I think we should add a specific CONTRIBUTING.md file for this repo (I volunteer to do it).

I would like to include things like:

So, I'm happy to prepare one, but I would like to get your thoughts @ekenes, @MikeMillerGIS, @VwakeM, @ted-howard, @jdcarls2, about some conventions I think we should define, specially about Adding a new expression.

My questions for you are:

  1. Should we specify a convention for file & folder names capitalization? (camelCase vs snake_case vs PascalCase vs or kebab-case) <- Any preference? 1.1. Should README.md always capitalized? (example) 1.2. Is it OK to use special characters like "(", ")", ... (example)
  2. If an expression is too long, is it recommended keeping it in a *.js file instead of the markdown file? (example)
  3. Should we add images and sample data within folders? (e.g. images/ & sample-data/). I have seen some folders like attribute_rule_calculation with ton of files.
  4. I sometimes see we have folders grouping expressions (example). Should they have their own README.md and list the expressions there instead of in the parent README file? (Barcode example)
  5. Should we request a local copy of the data as a static file? https://gdb.zip/ 5.1. If so, should we use specific extensions? (e.g. gdb.zip vs zip vs ...; stylx)
  6. Do we need to add. Contributing and License to all README.md files?

My proposal:

  1. I would vote for kebab-case 1.1. Yes, I would recommend README.md (capitals) 1.2. I would say avoid \/:*?"<>|
  2. I'm not against that, but if so, I would place it in a expressions folder with the same name as the markdown file
  3. I would say yes, use folders.
  4. I would say yes. Add a single link in the parent README.md to the child README.md and list the expressions there
  5. I would say it is recommended whenever possible, and set [extension].zip meaning .gdb.zip, .stylx.zip, ...
  6. I would say no.

Thanks in advance! 😊

P.S. sorry if I added or missed someone here, please let me know if that's the case.

hhkaos commented 11 months ago

To move things forward, I have already made a PR. I look forward to your comments 😄