Skip to content

Latest commit

 

History

History
203 lines (130 loc) · 6.3 KB

CONTRIBUTING.md

File metadata and controls

203 lines (130 loc) · 6.3 KB
Raw

Contribution Guidelines

Issues and bug reports

If you see unexpected behavior with this project, please create an issue on GitHub with the following information:

  • A title and a clear description of the issue.
  • The project version (for example "0.1.4").
  • The framework version (for example "Node.js 8.11.3").
  • The browser version (for example "Chrome 67.0.3396.99").

If possible, include the following to help us reproduce the issue:

  • A code sample that demonstrates the issue.
  • Any unit test cases that show how the expected behavior is not occurring.
  • An executable test case.

If you have a question about Splunk, see Splunk Answers.

Code formatting and styling

We recommend the following tools for formatting and styling JavaScript code:

Development environment for Mac OS X

This section describes recommended tools for the Mac OS X development environment.

Install development tools

We recommend the Homebrew package manager for *nix development environments.

Run the following command to install Homebrew:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Next, run the following command to update Homebrew:

brew update

Use Homebrew to install additional tools:

  • Node.js, a JavaScript runtime

    brew install node

  • Yarn, a dependency manager

    brew install yarn

Install Docker, a container platform. For installation details, see Install Docker Desktop for Mac on the Docker Docs website.

Development environment for Windows

Several of the npm scripts in this repository contain shell scripts targeting Bash. If you are developing on Windows consider installing the following:

Configure the repository environment

To install JavaScript dependencies, run the following command from the root of the project repository:

yarn

Developing with dependent packages

When working with packages within the mono-repo that depend on each other, you must symlink the packages using the @lerna/link command as follows:

yarn lerna link

Git commit conventions

Follow the Conventional Commits format for Git commit messages. Using the format makes the commit history for the project more readable and generates a changelog automatically.

To enforce formatting of commit messages, use the Commitizen CLI wizard:

  1. After staging your changes, run the following command:

    yarn run commit

  2. Follow the prompts to finish formatting your commit messages.

Commit message format

Use the following format for commit messages:

<type>(<scope>): <subject>
<blank_line>
<body>
<blank_line>
<footer>

Use one of the following values for "type":

type Description
feat A new feature
fix A bug fix
docs Documentation-only changes
style Changes that do not affect the meaning of the code
refactor A code change that neither fixes a bug nor adds a feature
release An aggregation of code changes to be used for a release
perf A code change that improves performance
test A code change that adds, updates, or fixes tests
ci A code change in the CI pipeline
revert Revert to a commit

Scopes are broken down at the package level. The value for "scope" must be one of the following:

  • cloud-auth-client
  • cloud-auth-common
  • cloud-auth-node

Note: If your changes do not apply to any of the scopes above, or if your changes affect more than one scope, use a scope value of "*".

Subject and body rules

For the subject of the commit message, use a short description of the change:

  • Start the description with present tense (for example, "add", not "added" nor "adds").
  • Don't capitalize the first letter.
  • Don't include references to JIRA tickets or GitHub issue numbers.

For the body of the commit, follow the rules above and include detailed descriptions of the code changes.

Submit a pull request

  1. Fill out the Splunk Contribution Agreement.

  2. Configure your development environment as described above.

  3. Create a new branch. For example:

    git checkout -b my-branch develop

  4. Make code changes in your branch with tests, using the code formatting and styling tools listed above.

  5. Check for lint errors.

    yarn run tslint

  6. Commit your changes. Be sure to adhere to the Conventional Commits format.

    yarn commit

  7. Push your branch to GitHub.

    git push origin my-branch

  8. In GitHub, create a pull request that targets the develop branch. CI tests are run automatically.

  9. After the pull request is merged, delete your branch.

  10. Pull changes from the develop branch.

    git checkout develop
git pull develop

Generate documentation

To generate documentation, enter the following command:

yarn ts:docs

Contact us

If you have questions, reach out to us on Slack in the #sdc channel or email us at sdcbeta@splunk.com.