Skip to content

Latest commit

 

History

History
126 lines (88 loc) · 7.61 KB

CONTRIBUTING.md

File metadata and controls

126 lines (88 loc) · 7.61 KB

Contribution Guidelines

As a community, we want to help each other, provide constructive feedback, and make a better product. Of course, our code of conduct must be followed at any time.

Consumer Expectations

NUKE is a personal project that was made open-source to let the whole community benefit from it free of charge but also "as is". Like a lot of open-source projects, it is primarily maintained and developed by a single person. Some of the most time-consuming tasks around the project are:

  • Development of the NuGet package itself (C#, .NET, MSBuild)
  • Collecting CLI metadata (.NET ClI, MSBuild, Docker, +30 others)
  • Integration with CI/CD services (Azure Pipelines, GitHub Actions, TeamCity, ...)
  • IDE extensions (VSSDK, ReSharper SDK, IntelliJ SDK, Kotlin, JVM, Gradle)
  • Website (JavaScript, TypeScript, React, Docusaurus)
  • Hosting (Azure, Cloudflare, Algolia, Fathom)
  • Documentation, presentation slides, and blog posts
  • Helping in GitHub issues/discussions, Slack, and Discord
  • Talking at conferences and meetups including travel
  • Promotion on Twitter and Mastodon

This list should give you an impression of what it took to make NUKE what it is today and what it continuously takes to move it forward. Obviously though, there's only a limited amount of time a single person can dedicate besides their personal life and real job without burning out.

Therefore, everything that benefits a larger audience is prioritized over digging into issues that only affect a single or few individuals. Please don't take offense when your issue or pull-request is not getting the attention you were hoping for. It is simply a time management decision.

Baseline Contributions

There are a number of minimal to zero efforts you can make to show your support for the project:

The above points are considered somewhat of the norm in exchange for using the project free of charge.

Sustainability Contributions

There are plenty of ways to show your commitment to the project and strengthen its longevity. These are typically tied to contributing time or money, but also allow for prioritizing your individual issues in return:

  • Convince your company to sponsor
  • Sponsor personally (e.g., when the project improves your work performance reviews)
  • Fix or investigate issues that are marked as good first issue
  • Take ownership for a tool wrapper or CI/CD service (.NET CLI, GitHub Actions, ...)
  • Write a blog post or give a meetup talk (let us know!)
  • Help others in GitHub issues/discussions or on Slack and Discord

If you need help with any of the above suggestions, don't hesitate to ask!

Issues

Before creating an issue

Evaluate whether your topic is going to be a valid issue:

  • Have you read and searched the documentation?
  • Have you checked the FAQ?
  • Is your issue more of a question? Ask on GitHub discussions, Slack, or Discord!
  • Have you checked existing/closed issues? Maybe your version is behind?
  • Did you verify it's not an external tool issue? Invoke the command manually!
  • Don't file issues for tool wrappers. Send a pull-request instead!
  • Refrain from debating the governance or state of the project out of your own interests (see consumer expectations & sustainability contributions)

When creating an issue

Choose one of the issue templates and fill it out as good as possible. This includes, but is not limited to:

When an issue is of poor quality, or it is evident that the guidelines haven't been read, it will be closed without any further response.

After creating an issue

Once the triage label is removed from your issue, you will know how it is seen from the project's perspective:

  • Issues labelled as area:cicd or area:tools usually can be fixed in user code
    • Custom arguments can be wrapped in local extension methods
    • Additional steps in CI/CD configuration generation can be added through inheritance
  • If your issue is labelled as good first issue, consider sending a pull-request

Depending on the priority, available time, and your personal commitment to the project, the issue will be addressed sooner or later. In (hopefully) rare cases, it might also be closed due to missing resources.

Pull-Requests

Before creating a pull-request

In your own interest of getting a pull-request merged (timely):

  • Discuss non-trivial changes in an issue
  • Make sure your employer allows contributions
  • Branch your work off from the develop branch
  • Get familiar with the coding conventions

When working on a pull-request

  • Aim for qualitative and readable code
  • Follow the coding style of the existing codebase
  • Make sure the project builds and all tests pass
  • Don't copy/paste chunks of code, even when it's meant as a draft
  • Drafting APIs is okay, as long as you're ready to finish it later
  • Add tests when meaningful, particularly when there is a related test class already

When creating a pull-request

For tool wrappers (e.g. .NET CLI), also note the following remarks:

  • Copy/paste as much as possible
  • Cover at least a full command with all its arguments
  • Use tags for formatting in help
    • <c> for inline code
    • <a> for links
    • <ul>/<ol> for lists
    • <em> for emphasized text
    • <para/> in between paragraphs (as opposed to <p>...</p>)
  • Don't explicitly define secret: false (it's the default)
  • Don't provide default: xxx (it's obsolete)
  • Don't generate the code; it will be done manually once per release

After creating a pull-request