Skip to content

Latest commit

 

History

History
91 lines (66 loc) · 6.95 KB

CONTRIBUTING.md

File metadata and controls

91 lines (66 loc) · 6.95 KB

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Table of Contents:

I want to contribute, what should I work on?

You can help mostly by:

  • Suggesting ideas for Arcade expressions by creating a Expression request issue1.
  • Reporting problems with existing expressions by creating a Bug issue.
  • Working on the issues marked as help wanted. There is also a good first issue label if you are just getting started.
    • Comment on the issue and check if any additional context is needed before you start working. This will also help everyone knows that you are already working on it.

(1): If you are looking for inspiration of example expressions, you can search in different places such as: ArcGIS Online "Arcade Expressions and You", Arcade questions at Esri Community, articles, videos, or documentation pages (e.g. Arcade samples within the ArcGIS Maps SDK for JavaScript).

Before creating and issue

  • If something isn't working the way you expect, take a look at the existing issues before logging a new one.
  • If you have a general question about Arcade, please check the arcade tag at Esri Community, or go to the right place where you can ask questions, and collaborate with others.
  • Provide all of the requested info from the appropriate issue template.
  • Other things to consider when filling a bug issue(so we can work on resolving the issue as soon as possible):
    • Use a clear and descriptive title.
    • Detail what is happening now vs what should happen.
    • Tell us how to reproduce the issue (e.g. is it happening in a specific profile, browser, ...?).
    • Can it be reliably reproduced? If not, tell us how often it happens and under what circumstances.
    • Provide a sample that reproduces the issue whenever possible.
    • Screenshots, GIFsn and screen recordings are our friends!
    • Did this problem start happening after a recent release or was it always a bug?

Getting a development environment set up

You can make use of the ArcGIS Arcade Playground if you need it, but to use this repository you don't need a special configuration, just run the expression in one of the supported products.

Adding a new expression

  • Each expression lives in a markdown file. We have prepared a template file with all information it should include.
  • Use kebab-case to name files and folders, and avoid special characters: \/:*?"<>|.?.
  • README.md files are the only exception.
  • Include reference files in images/ and sample-data within the same parent folder as the expression.
    • Use the same name as the markdown file. If several are needed, use the name as a prefix (e.g. create-lateral-prototype.js and create-lateral-devsummit2023.js).
    • Compress sample data files using ZIP and leave the original extension in the file name (e.g. file-name.gdb.zip, file-name.stylx.zip, ...).
  • If you are grouping several expressions within a folder, include a README.md using readme-template.md, and follow all conventions above.
    • Include a single link from the parent README.md to the new README.md.

Commit message format

This project do not strictly follows conventional commits, but we will use the format <type>: description [optional #issue-number]. Be sure to provide clear and sufficient information in commit messages.

For <type> you should use:

  • feat: A new expression
  • fix: A bug fix within an expression
  • docs: Documentation only changes (changes in markdown)
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature

description:

  • The subject contains succinct description of the change
  • use the imperative, present tense: "change" not "changed" nor "changes"
  • do not capitalize first letter
  • do not place a period . at the end
  • entire length of the subject must not go over 50 characters
  • describe what the commit does, not what issue it relates to or fixes
  • be brief, yet descriptive - we should have a good understanding of what the commit does by reading the subject

Examples:

  • fix: adds some calculation attribute rules related to work migrating attributes #11
  • doc: adds missing expressions to README files #77

Pull requests

Before each PR follow remember:

  • Updating the list of expressions in the README.md within the same folder.
  • Link your PR to an issue if it exists. Use a supported keyword in the pull request description. Ex."Closes #10" or "Fixes #10" (more).