All information related to ECS is versioned in the elastic/ecs repository. All changes to ECS happen through Pull Requests submitted through Git.
ECS is an open source project and we love to receive contributions from our community - you!
- How to Contribute
- Git and Github Guidelines
- Feature freezes and branching
- Documentation
- Schema Files
- Additional Resources
There are two primary ways in which you can contribute to ECS.
- The RFC process is used for significant additions or breaking changes to the schema itself.
- For bug fixes or incremental, non-controversial additions to ECS, changes can be made directly to the ECS project and submitted as pull request.
You need these tools to contribute to the ECS repo:
- Sign the Contributor License Agreement.
- Set up your git environment.
- Create your own fork of the ECS repo.
- Clone your fork to your machine.
- Create a local branch to hold your changes.
- Run
git checkout -b branch-name
, wherebranch-name
is the name you want to give your local branch
- Run
- Do your work.
- Schema changes will be done in the
.yml
files under theschemas
directory. Review the Schema Files section below. - Generator scripts and other tooling reside in the
scripts
directory. - Generated artifacts fall under the
generated
directory. - Documentation files are located in the
docs
directory.
- Schema changes will be done in the
- Run
make
to update generated files. - If necessary, make sure tests pass.
- Run
make test
- Add tests for your changes, if necessary
- Run
- Commit your changes locally.
- Run
git commit -a -m "your message"
- Run
- Push your changes to your own github.com fork.
- Run
git push --set-upstream origin branch-name
- In this command,
origin
is an alias that references your fork.
- Run
- Request feedback about your changes.
- Create a Pull Request against the ECS repo.
- (Look for the
Compare & pull request
button on your branch in github.com.)
- (Look for the
- Add an entry to CHANGELOG.next.md.
- Wait for reviews on your PR.
- Incorporate review comments and push updates if needed.
- Create a Pull Request against the ECS repo.
- Thank you for your contribution!
Important: Be sure to push changes only to your own fork. Changes must be approved before they are merged into the main repository.
We follow the Github forking model for collaboration in the ECS repo. Typically contributors will add a remote repository called upstream
to point to the Elastic ECS repo to add latest changes from the repo to their fork.
- When submitting a PR for review, please perform and interactive rebase to clean up the commit history. A logical commit history is easier for reviewers to follow.
- Use meaningful and helpful commit messages on your changes and an explanation of why you made those changes.
- When merging, maintainers will squash your commits into a single commit.
Please follow these guidelines when submitting PRs:
- Include an explanation of your changes in the PR description.
- Links to relevant issues, external resources, or related PRs are helpful and useful.
- Update any tests or add new tests where appropriate.
Please follow these guidelines when submitting Issues:
- Go to the ECS repo: https://github.com/elastic/ecs
- Click
Issues
in the nav bar under the repo name. - Click
New issue
. Provide as many details as possible to help reviewers and other contributors understand your proposal. - Add your text, and click
Submit new issue
.
ECS follows a two-stage feature freeze approach using the concepts of Soft Feature Freezes (SFF) and Hard Feature Freezes (HFF).
Once a branch enters SFF, only minor and low-impact features can be added. The ECS team will rely on the “scope of impact” assessment in the ECS RFC process to help assess the potential impact of a proposed change.
When a branch enters HFF, from that point onward all new features of any size must be contributed to the next ECS version.
For people contributing to the ECS repo, this change means there are two branches at any given time that are accepting at least some sort of feature changes. Here's an example using ECS 8.1:
Branch | Version | Change scope |
---|---|---|
main |
8.2 | Any enhancements or otherwise |
8.1 |
8.1 | SFF: Can have low impact enhancements |
8.0 |
8.0 | HFF: Only bug fixes, tooling, docs, etc |
ECS maintains two changelog files:
- CHANGELOG.md contains a list of notable changes for each released version of ECS.
- CHANGELOG.next.md contains a list of unreleased ECS changes.
Breaking changes intended for the next major version should be included underneath the Breaking changes
sections in CHANGELOG.next.md
.
ECS maintains multiple release branches in the repo. The main
branch is where all new contributions should be submitted, and features and bug fixes will be backported into other branches when appropriate. Any backporting needs will be handled by the ECS team.
Refer to the backport tool's repo for requirements and install guide. A project config is maintained in the root of this repo.
Run:
$ npx backport --pr 1234
Select target branch(es) to backport to:
? Select commit #1234 (cb79e8f5)
? Select branch (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◯ 8.1
◯ 8.0
◯ 1.12
...
New PR(s) will be opened against the targeted branch(es).
ECS documentation is written in asciidoc format in the docs/
directory.
To build the docs and open them in your browser:
make docs
The following files are generated based on the current schema using Jinja templates:
File | Template |
---|---|
fields.asciidoc | fields_template.j2 |
fields-values.asciidoc | field_values_template.j2 |
field-details.asciidoc | field_details.j2 |
Running make
will update these files using the scripts/generators/asciidoc_fields.py generator. These doc files should not be modified directly. Any changes as a result of a schema update and subsequent run of make
should be committed.
Jinja templates allow for formatting or styling changes to templates without needing to modify the generator script directly. Some details about the Jinja template engine and our implementation are covered below as a primer; the full syntax and semantics of Jinja is covered in the project's documentation.
- Statements:
{% ... %}
- Expressions:
{{ ... }}
- Comments:
{{# ... #}}
Whitespace can be stripped by adding the minus sign (-
) to the start or end of a block. Adding -
to the start or end of a block will remove the whitespace before or after that block.
{% for i in numbers -%}
{{i}}
{%- endfor %}
All elements would be rendered without any separating whitespace. If numbers
is list of numbers from 0
to 9
, the output would be 0123456789
.
Templates variables are passed to the template by the application. Typically these will either be used in an expression or within a control structure statement (e.g. a for
loop). In the below example, users
is passed into the template and is iterated over with a for
loop.
<ul>
{% for user in users %}
<li>{{ user }}</li>
{% endfor %}
</ul>
The @templated('template_file_name')
decorator is used to inject the additional functionality that renders and returns the template's content to the generator. Decorated functions should return a dict used to generate the template. When the decorated function returns, the dictionary is passed to the template renderer.
@templated('fields_template.j2')
def page_field_index(intermediate_nested, ecs_version):
fieldsets = ecs_helpers.dict_sorted_by_keys(intermediate_nested, ['group', 'name'])
return dict(ecs_version=ecs_version, fieldsets=fieldsets)
The schemas directory contains the files which define the Elastic Common Schema data model. The file structure is documented in schemas/README.md. Field additions and modifications will be made to the schemas/*.yml
files.
Users consuming ECS to generate something for other use cases should use the generated/ecs/*.yml
files. More detail can be found here.