Contributions are very welcome, these can include documentation, bug reports, issues, feature requests, feature implementations or tutorials.
We have good first issues for new contributors. These are issues that we've identified as good starting points for getting acquainted with our codebase, styleguide or working with Go.
- Reporting Issues
- Code Contribution Guidelines
- Setting up a dev environment
- Development
- Release
- Helpers
- Resources
If you have found an issue or defect in ecctl
or the latest documentation, use the GitHub issue tracker to report the problem. Make sure to follow the template provided for you to provide all the useful details possible.
For the benefit of all and to maintain consistency, we have come up with some simple guidelines. These will help us collaborate in a more efficient manner.
-
Unless the PR is very small (e.g. fixing a typo), please make sure there is an issue for your PR. If not, make an issue with the provided template first, and explain the context for the change you are proposing.
Your PR will go smoother if the solution is agreed upon before you've spent a lot of time implementing it. We encourage PRs to allow for review and discussion of code changes.
-
We encourage PRs to be kept to a single change. Please don't work on several tasks in a single PR if possible.
-
When you're ready to create a pull request, please be sure to:
-
Adhere to the project's style guide.
-
Make sure you've signed the Elastic CLA.
-
Have test cases for the new code. If you have questions about how to do this, please ask in your pull request.
-
Run
make format
,make lint
andmake meta-lint
. -
In case you are adding/modifying command(s) run
make docs
to ensure that they are updated accordingly. -
Ensure that unit tests succeed with
make unit
. -
Use the provided PR template, and assign any labels which may fit your PR.
-
There is no need to add reviewers, the code owners will be automatically added to your PR.
-
The codebase is maintained using the "contributor workflow" where everyone without exception contributes patch proposals using "pull requests". This facilitates social contribution, easy testing and peer review.
To contribute a patch, make sure you follow this workflow:
- Fork repository
- Enable GitHub actions to run in your fork
- Create topic branch
- Commit patches
In general commits should be atomic and diffs should be easy to read.
Commit messages should be verbose by default consisting of a short subject line (50 chars max). A blank line and detailed explanatory text as separate paragraph(s), unless the title alone is self-explanatory ("trivial: Fix comment typo in main.go"). Commit messages should be helpful to people reading your code in the future, so explain the reasoning for your decisions. Further explanation here.
If a particular commit references another issue, please add the reference. For example: refs #123 or fixes/closes #1234. Using the fixes or closes keywords will cause the corresponding issue to be closed when the pull request is merged.
Example:
elasticsearch: Remove unnecessary cluster list sorting
Removes the unnecessary sorting on the obtained API response since the
cluster list is already sorted by the backend.
Closes #1234
Pull requests that contain changes on the code base and related documentation, e.g. for a new feature, shall remain a single, atomic one.
The title of the pull request should be prefixed by the package or area that the pull request affects. Any change that affects a package in general must be prefixed by its name. Valid areas as:
- docs: Changes for documentation related to the project
- ci: Changes for the CI build system.
- scripts: Changes that affect ancillary scripts or the Makefile
- trivial: should only be used for PRs that do not change generated executable code. Notably, refactors (change of function arguments and code reorganization) and changes in behaviour should not be marked as trivial. Examples of trivial PRs are changes to:
- comments
- whitespace
- variable names
Example:
elasticsearch: Remove unnecessary cluster list sorting
docs: Improve the contributor documentation
trivial: Fix a couple of typos on elasticsearch.List
If a pull request is not to be considered for merging (yet), please prefix the title with [WIP] or use Tasks Lists in the body of the pull request to indicate tasks are pending.
The body of the pull request should contain a detailed description about what the patch does, along with any justification/reasoning. You should include references to any related discussions (for example other tickets or mailing list discussions).
At this stage one should expect comments and review from other contributors. You can add more commits to your pull request by committing them locally and pushing to your fork until you have satisfied all feedback.
To start off you will need to have Go 1.11 or higher installed. Make sure you also have the environment variables $GOPATH
and $GOBIN
($GOPATH/bin
) defined. If you need assistance with this please follow golangbootcamp guide.
ecctl
uses go modules to version dependencies, make sure you've got the GO111MODULE=on
environment variable set to leverage go modules. Running go get
in the root folder will download all the required dependencies.
Due to the way Go handles package imports, the best approach for working on a ecctl
fork is to use Git Remotes. Here's a simple walk-through for getting started:
-
Fetch the sources with
go get -d github.com/elastic/ecctl
-
Change to the source directory:
cd ${GOPATH}/src/github.com/elastic/ecctl
-
Rename the remote to
upstream
:git remote rename origin upstream
-
Fork
ecctl
in GitHub. -
Add your fork as a new remote and name it
origin
:# For SSH based credentials git remote add origin [email protected]:USERNAME/ecctl.git # For https based credentials git remote add origin https://github.com/USERNAME/ecctl
-
Verify your Git remotes with
$ git remote -v
. The result should be something like this:origin [email protected]:USERNAME/ecctl.git (fetch) origin [email protected]:USERNAME/ecctl.git (push) upstream [email protected]:elastic/ecctl (fetch) upstream [email protected]:elastic/ecctl (push)
-
Create a new branch for your changes (the branch name is arbitrary):
git checkout -b issue1234
-
After making your changes, commit them to your new branch:
git commit -a -v -s
-
Push the changes to your new remote:
git push --set-upstream origin issue1234
-
You're now ready to submit a PR based upon the new branch in your forked repository.
We have a detailed guide that provides step-by-step instructions on adding a new command to ecctl.
There's two variables that can be passed to the Makefile target:
TEST_UNIT_FLAGS
args controls the flags that are sent togo test
.TEST_UNIT_PACKAGE
controls which package names to test (defaults to./...
which means all packages).
The current TEST_UNIT_FLAGS
default to: -timeout 10s -p 4 -race -cover
.
For a complete list of all the go test
flags see Testing flags.
For a complete list of all the go build
flags see Compile packages and dependencies.
Flag | Description |
---|---|
-timeout |
controls the max runtime for a set of unit tests in a package. |
-p |
controls the number of package tests to run concurrently. |
-count |
number of times that the unit tests for a package will be run. |
-race |
enables race condition detection during test execution. |
-cover |
displays the test coverage for each package. |
Examples:
$ make unit
-> Running unit tests for ecctl...
...
$ make unit TEST_UNIT_PACKAGE=github.com/elastic/ecctl/formatter
-> Running unit tests for ecctl...
ok github.com/elastic/ecctl/formatter 1.164s coverage: 49.7% of statements
Since ecctl
heavily relies on cloud-sdk-go
, There might be times when the dependencies are out of date, in that case, it's the contributor's responsibility to update the dependencies and reflect that on the go.mod
file.
cloud-sdk-go
and ecctl
almost go hand-in-hand, meaning that in some cases you might want to test how these dependencies affect ecctl
.
Using make fake-sdk
will remove the versioned cloud-sdk-go
and use the local copy of cloud-sdk-go
which is assumed to be in ../cloud-sdk-go
.
Remember to remove the replace
directive from go.mod
before committing your changes. make remove-fake-sdk
will take care of that for you.
If the contributing work you're doing involves changing or creating new output templates, you'll need
to work with 2 makefile targets, bindata
and bindata-dev
.
This target packages the template files inside formatter/templates
so that they can be distributed with the executable
binary that the build target creates. You'll have to run this command before committing your changes.
This target is aimed to be used when you're developing so that every time that you modify a template you don't have to run
make bindata
, instead bindata-dev
will open the template files from disk every time instead of loading the file data
into a variable.
Note: Remember to run make bindata
before committing your changes
Make sure you have followed through the environment setup requisites
To build a temporary binary inside your project's root run:
cd ${GOPATH}/src/github.com/elastic/ecctl
make ecctl
See the release guide.
There's a bunch of bundled helpers in scripts, make sure to source them to have them loaded in your environment.
. scripts/helpers.sh
There's a helper that's worth a mention; dev-cli
is ready to use with autocompletion after
the helpers have been sourced.
dev-cli
is a function that runsgo run main.go
behind the scenes.reload_helpers
will source the contents of the helpers again.dump-ecctl-vars
is useful to while debugging specific behaviour of ecctl to see which ecctl specific environment variables are set.