CONTRIBUTING.md

Contributing

Table of Contents

• Use This Guide?
• Ask or Say Something?
  • Request Support
  • Report an Error or Bug
  • Report a security concern
  • Request a Feature
• Make Something?
  • Submitting a Pull Request
  • Project Setup
  • Contribute Documentation
  • Contribute Code
• Manage Something
  • Provide Support on Issues
  • Label Issues
  • Clean Up Issues and PRs
  • Review Pull Requests
  • Merge Pull Requests
  • Tag a Release
  • Join the Project Team
• Add a Guide Like This One To My Project?

Introduction

Thank you for your interest in contributing! All types of contributions are encouraged and valued. See the table of contents for different ways to help and details about how this project handles them.

Please make sure to read the relevant section before making your contribution. It will make it a lot easier for project maintainers to make the most of it and smooth out the experience for all involved.

The Project Team looks forward to your contributions.

Request Support

If you have a question about this project, how to use it, or just need clarification about something:

• Open an Issue
• Provide as much context as you can about what you're running into
• Provide project and platform versions (NATLAS_VERSION, OS version, etc), depending on what seems relevant. If not, please be prepared to provide this information upon further inquiry.

Once the issue is filed:

• The project team will label the issue.
• Someone will try to respond as soon as possible.
• If you or the maintainers don't respond to an issue for 30 days, the issue may be closed. If you want to come back to it, reply to the issue and we will reopen it. Please avoid creating a new issue as an extension of one you've already made.

Report an Error or Bug

If you run into an error or bug with the project:

• Open an Issue
• Provide reproduction steps that someone else can follow to recreate the bug or error on their own.
• Provide project and platform versions (NATLAS_VERSION, OS version, commit hash, etc), depending on what seems relevant. If not, please be prepared to provide this information when asked for it.

Once the issue is filed:

• The project team will label the issue.
• A team member will try to reproduce the issue with your provided steps. If there are no repro steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as needs-repro. Bugs with the needs-repro tag will not be addressed until they are reproduced.
• If the team is able to reproduce the issue, it will be marked needs-fix, as well as any other tags that are relevant (such as agent or server), and the issue will be left to be implemented by someone.
• If you or the maintainers don't respond to an issue for 30 days, the issue may be closed. If you want to come back to it, reply to the issue and we will reopenit. Please avoid creating a new issue as an extension of one you've already made.

Request a Feature

If the project doesn't do something you need or want it to do:

• Open an Issue
• Provide as much context as you can about what you'd like it to do.
• Please try and be clear about why existing features and alternatives would not work for you.

Once it's filed:

• The project team will label the issue.
• The project team will evaluate the feature request, possibly asking you more questions to understand its purpose and any relevant requirements. If the issue is closed, the team will convey their reasoning and suggest an alternative path forward.
• If the feature request is accepted, it will be marked for implementation by being assigned a milestone, which can then be done by either by a core team member or by anyone in the community who wants to contribute code.

Note: The team is unlikely to be able to accept every single feature request that is filed. Please understand if they need to say no.

Submitting a Pull Request

Pull requests should be submitted against the main branch. Branch protection rules should enforce that your pull request is up to date before being merged. All development, including that of the maintainers, SHOULD be done through the fork + pull-request pattern.

Project Setup

So you wanna contribute some code! That's great! This project uses GitHub Pull Requests to manage outside contributions, so read up on how to fork a GitHub project and file a PR if you've never done it before.

If this seems like a lot or you aren't able to do all this setup, you might also be able to edit the files directly without having to do any of this setup. Yes, even code.

If you want to go the usual route and run the project locally, though:

• Be using an ubuntu-based development environment
• Fork the project
• Download and install docker desktop.
  • Windows
  • Mac
  • Ubuntu
• Install docker-compose
  • All Operating Systems
• Read Getting started with Docker
• Modify the code
• Run docker-compose up -d
• Before you're ready to commit, install the prerequisite pre-commit hooks.
  • From the root of the natlas repository, pipenv install to install dev dependencies
  • pipenv run pre-commit install to install the precommit hooks into your .git directory
  • pipenv run pre-commit run --all-files to ensure that the hooks work correctly before committing
• If your code passes the pre-commit hooks, you're ready to commit!
• Commit and push to your fork and then open a pull request
• A series of checks will automatically run against your pull request. These must all pass in order for your PR to be accepted.

Coding Conventions

• Code must be black formatted
• Code must pass flake8 using the supplied .flake8 file
• Code must pass all supplied pre-commit hooks

Contribute Documentation

Documentation is a super important, critical part of this project. Docs are how we keep track of what we're doing, how, and why. It's how we stay on the same page about our policies. And it's how we tell others everything they need in order to be able to use this project -- or contribute to it. So thank you in advance.

Documentation contributions of any size are welcome! Feel free to file a PR even if you're just rewording a sentence to be more clear, or fixing a spelling mistake!

To contribute documentation:

• Set up the project.
• Edit or add any relevant documentation.
• Make sure your changes are formatted correctly and consistently with the rest of the documentation.
• Re-read what you wrote, and run a spellchecker on it to make sure you didn't miss anything.
• Write clear, concise commit message(s).
• Open a new pull request with your changes.
• If your PR is connected to an open issue, add a line in your PR's description that says Fixes: #123, where #123 is the number of the issue you're fixing.

Once you've filed the PR:

• One or more maintainers will use GitHub's review feature to review your PR.
• If the maintainer asks for any changes, edit your changes, push, and ask for another review.
• If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly.
• If your PR gets accepted, it will be marked as such, and merged into the main branch soon after. Your contribution will be distributed to the masses next time the maintainers tag a release

Contribute Code

We like code commits a lot! They're super handy, and they keep the project going and doing the work it needs to do to be useful to others.

Code contributions of just about any size are acceptable!

To contribute code:

• Set up the project.
• Make any necessary changes to the source code.
• Include any additional documentation the changes might need.
• Write or show tests that verify that your contribution works as expected.
• Write clear, concise commit message(s).
• Open a new pull request with your changes.
• If your PR is connected to an open issue, add a line in your PR's description that says Fixes: #123, where #123 is the number of the issue you're fixing.

Once you've filed the PR:

• One or more maintainers will use GitHub's review feature to review your PR.
• If the maintainer asks for any changes, edit your changes, push, and ask for another review. Additional tags will be added depending on the review.
• If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly.
• If your PR gets accepted, it will be marked as such, and merged into the main branch soon after. Your contribution will be distributed to the masses next time the maintainers tag a release.

Provide Support on Issues

Needs Collaborator: none

Helping out other users with their questions is a really awesome way of contributing to any community. It's not uncommon for most of the issues on an open source projects being support-related questions by users trying to understand something they ran into, or find their way around a known bug.

Sometimes, the support label will be added to things that turn out to actually be other things, like bugs or feature requests. In that case, suss out the details with the person who filed the original issue, add a comment explaining what the bug is, and change the label from support to bug or enhancement. If you can't do this yourself, @mention a maintainer so they can do it.

In order to help other folks out with their questions:

• Go to the issue tracker and filter open issues by the support label.
• Read through the list until you find something that you're familiar enough with to give an answer to.
• Respond to the issue with whatever details are needed to clarify the question, or get more details about what's going on.
• Once the discussion wraps up and things are clarified, either close the issue, or ask the original issue filer (or a maintainer) to close it for you.

Some notes on picking up support issues:

• Avoid responding to issues you don't know you can answer accurately.
• As much as possible, try to refer to past issues with accepted answers. Link to them from your replies with the #123 format.
• Be kind and patient with users -- often, folks who have run into confusing things might be upset or impatient. This is ok. Try to understand where they're coming from, and if you're too uncomfortable with the tone, feel free to stay away or withdraw from the issue. (note: if the user is outright hostile or is violating the CoC, refer to the Code of Conduct to resolve the conflict).

Label Issues

Needs Collaborator: Issue Tracker

One of the most important tasks in handling issues is labeling them usefully and accurately. All other tasks involving issues ultimately rely on the issue being classified in such a way that relevant parties looking to do their own tasks can find them quickly and easily.

In order to label issues, open up the list of unlabeled issues and, from newest to oldest, read through each one and apply issue labels according to the table below. If you're unsure about what label to apply, skip the issue and try the next one: don't feel obligated to label each and every issue yourself!

Label	Apply When	Notes
agent	Applies to issues or pull requests that affect natlas-agent code.
bug	Cases where the code (or documentation) is behaving in a way it wasn't intended to.	If something is happening that surprises the user but does not go against the way the code is designed, it should use the enhancement label.
critical	Added to bug issues if the problem described makes the code completely unusable in a common situation.
dependencies	Added to pull requests that update a dependency file.	Most commonly done to bump versions for security fixes.
documentation	Added to issues or pull requests that affect any of the documentation for the project.	Can be combined with other labels, such as bug or enhancement.
duplicate	Added to issues or PRs that refer to the exact same issue as another one that's been previously labeled.	Duplicate issues should be marked and closed right away, with a message referencing the issue it's a duplicate of (with #123)
enhancement	Added to feature requests, PRs, or documentation issues that are purely additive: the code or docs currently work as expected, but a change is being requested or suggested.
help wanted	Applied by Committers to issues and PRs that they would like to get outside help for. Generally, this means it's lower priority for the maintainer team to itself implement, but that the community is encouraged to pick up if they so desire	Never applied on first-pass labeling.
in-progress	Applied by Committers to PRs that are pending some work before they're ready for review.	The original PR submitter should @mention the team member that applied the label once the PR is complete.
invalid	Applied to issues or PRs that don't seem right for one reason or another.
performance	This issue or PR is directly related to improving performance.
refactor	Added to issues or PRs that deal with cleaning up or modifying the project for the betterment of it.
security	Applies to issues or PRs that deal with the security of the project.
server	Applies to issues or pull requests that affect natlas-server code
starter	Applied by Committers to issues that they consider good introductions to the project for people who have not contributed before. These are not necessarily "easy", but rather focused around how much context is necessary in order to understand what needs to be done for this project in particular.	Existing project members are expected to stay away from these unless they increase in priority.
support	This issue is either asking a question about how to use the project, clarifying the reason for unexpected behavior, or possibly reporting a bug but does not have enough detail yet to determine whether it would count as such.	The label should be switched to bug if reliable reproduction steps are provided. Issues primarily with unintended configurations of a user's environment are not considered bugs, even if they cause crashes.
wontfix	Labelers may apply this label to issues that clearly have nothing at all to do with the project or are otherwise entirely outside of its scope/sphere of influence. Committers may apply this label and close an issue or PR if they decide to pass on an otherwise relevant issue.	The issue or PR should be closed as soon as the label is applied, and a clear explanation provided of why the label was used. Contributors are free to contest the labeling, but the decision ultimately falls on committers as to whether to accept something or not.

Clean Up Issues and PRs

Needs Collaborator: Issue Tracker

Issues and PRs can go stale after a while. Maybe they're abandoned. Maybe the team will just plain not have time to address them any time soon.

In these cases, they should be closed until they're brought up again or the interaction starts over.

To clean up issues and PRs:

• Search the issue tracker for issues or PRs, and add the term updated:<=YYYY-MM-DD, where the date is 30 days before today.
• Go through each issue from oldest to newest, and close them if all of the following are true:
  • not opened by a maintainer
  • not marked as critical
  • not marked as starter or help wanted (these might stick around for a while, in general, as they're intended to be available)
  • no explicit messages in the comments asking for it to be left open
  • does not belong to a milestone
• Leave a message when closing saying "Cleaning up stale issue. Please reopen or ping us if and when you're ready to resume this. See Cleaning up Issues for more details."

Review Pull Requests

Needs Collaborator: Issue Tracker

While anyone can comment on a PR, add feedback, etc, PRs are only approved by team members with Issue Tracker or higher permissions.

PR reviews use GitHub's own review feature, which manages comments, approval, and review iteration.

Some notes:

• You may ask for minor changes ("nitpicks"), but consider whether they are really blockers to merging: try to err on the side of "approve, with comments".
• Please make sure you're familiar with the code or documentation being updated, unless it's a minor change (spellchecking, minor formatting, etc). You may @mention another project member who you think is better suited for the review, but still provide a non-approving review of your own.
• Be extra kind: people who submit code/doc contributions are putting themselves in a pretty vulnerable position, and have put time and care into what they've done (even if that's not obvious to you!) -- always respond with respect, be understanding, but don't feel like you need to sacrifice your standards for their sake, either. Just don't be a jerk about it, okay?

Merge Pull Requests

Needs Collaborator: Committer

Team members who can commit to the project are able to merge pull requests that have been reviewed and marked as approved. Please ensure that the pull request is targeting the latest main branch as defined in the instructions on submitting a pull request. At this point, you should attempt to merge the pull request in the following order:

1. Please create a merge commit to the main branch.
2. Under certain circumstances you may wish to squash and merge, but this should always be discussed with another maintainer if possible.

Tag A Release

Needs Collaborator: Committer

All releases to the natlas project should begin with a fork from the main branch. When a release is ready, ensure the CHANGELOG.md file is updat to date and the configs have been updated to reflect the new version. At this point, a new branch should be created. Once the new branch has been created, a tag for that commit should be created for v0.x.0. All new releases should increment the minor version field. The reason for branching is so that when we eventually need to patch a version to fix bugs, security or otherwise, we can increment the patch version off of the minor version branch.

This section will be filled out further after the next release is finished and it can be further automated and documented. The documentation for tagging a release is difficult to ensure accuracy until after we've tagged a release using the new workflow.

Join the Project Team

Ways to Join

There are many ways to contribute! Most of them don't require any official status unless otherwise noted. That said, there's a couple of positions that grant special repository abilities, and this section describes how they're granted and what they do.

All of the below positions are granted based on the project team's needs, as well as their consensus opinion about whether they would like to work with the person and think that they would fit well into that position. The process is relatively informal, and it's likely that people who express interest in participating can just be granted the permissions they'd like.

You can spot a collaborator on the repo by looking for the [Collaborator] or [Owner] tags next to their names.

Permission	Description
Issue Tracker	Granted to contributors who express a strong interest in spending time on the project's issue tracker. These tasks are mainly labeling issues, cleaning up old ones, and reviewing pull requests, as well as all the usual things non-team-member contributors can do. Issue handlers should not merge pull requests, tag releases, or directly commit code themselves: that should still be done through the usual pull request process. Becoming an Issue Handler means the project team trusts you to understand enough of the team's process and context to implement it on the issue tracker.
Committer	Granted to contributors who want to handle the actual pull request merges, tagging new versions, etc. Committers should have a good level of familiarity with the codebase, and enough context to understand the implications of various changes, as well as a good sense of the will and expectations of the project team.
Admin/Owner	Granted to people ultimately responsible for the project, its community, etc.

Attribution

This guide was created based on the WeAllJS CONTRIBUTING.md generator. Make your own!