Skip to content

Latest commit

 

History

History
145 lines (101 loc) · 5.63 KB

CONTRIBUTING.md

File metadata and controls

145 lines (101 loc) · 5.63 KB
Raw

How to Contribute

You can contribute to Playwright for .NET with issues and PRs.

Contribution Bar

Contributions must meet a certain standard of coding. To ensure this, the Project Maintainers perform regular Code Reviews. Additionally, a suite of tests runs for each PR.

DOs and DONT'Ts

Please do:

  • DO follow our coding style (C# code-specific)
  • DO include tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken.
  • DO keep the discussions focused. When a new or related topic comes up it's often better to create new issue than to side track the discussion.
  • DO blog and tweet (or whatever) about your contributions, frequently!

Please do not:

  • DON'T make PRs for style changes.
  • DON'T surprise us with big pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time.
  • DON'T commit code that you didn't write. If you find code that you think is a good fit to add, file an issue and start a discussion before proceeding.
  • DON'T submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.
  • DON'T add API additions without filing an issue and discussing with us first.

Breaking Changes

Playwright is evergreen. Breaking Changes should not happen. If they do, they follow a strict process and should come from upstream.

Commit Messages

Commit messages should follow the Semantic Commit Messages format:

label(namespace): title

description

footer
  1. label is one of the following:
    • fix - playwright bug fixes.
    • feat - playwright features.
    • docs - changes to docs, e.g. docs(api.md): .. to change documentation.
    • test - changes to playwright tests infrastructure.
    • devops - build-related work, e.g. CI related patches and general changes to the browser build infrastructure
    • chore - everything that doesn't fall under previous categories
  2. namespace is put in parenthesis after label and is optional. Must be lowercase.
  3. title is a brief summary of changes.
  4. description is optional, new-line separated from title and is in present tense.
  5. footer is optional, new-line separated from description and contains "fixes" / "references" attribution to github issues.

Example:

fix(firefox): make sure session cookies work

This patch fixes session cookies in firefox browser.

Fixes #123, fixes #234

PR Feedback

Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.

One or more Microsoft team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".

There are lots of thoughts and approaches for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.

Development Workflow

Prerequisites

Before building the solution for the first time, you will need to download the drivers. You can do this by either running commands manually, or by using the provided script, if you have PowerShell installed on your system.

Initialize

When you get the repo, you need to initialize the submodules and download the driver to start work. To do this, you can call:

.\build.ps1 driver -prereqs

This will run the following commands:

git submodule update --init
dotnet tool install --global dotnet-format
dotnet run --project ./src/tools/Playwright.Tooling/Playwright.Tooling.csproj -- download-drivers --basepath .

Dotnet Format

To help with formatting, you can make use of dotnet format. All you have to do is run

dotnet format

The resulting code will follow our style guides. This is also enforced in our CI.

Writing Tests

  • Every feature should be accompanied by a test.
  • Every public api event/method should be accompanied by a test.

Running Tests Locally

Running tests

Tests can either be executed in their entirety:

dotnet test .\src\Playwright.sln

You can also specify a single test to run:

dotnet test .\src\Playwright.sln --filter Playwright.Tests.TapTests

Additionally, you can use the Test Explorer if you're using Visual Studio.

Generating the API & rolling the driver (upstream)

We use the generator, located upstream, to generate the interfaces from the "single source of truth". To help us keep track of versions, this repository has a submodule dependency to upstream.

Note: to simplify, this assumes you have PowerShell on your system. You can perform each of these steps manually, however.

To generate the API, identify the commit sha of the point in time you wish to roll to, and run

.\build.ps1 roll commitsha

This will essentially run the following:

cd playwright
git checkout commitsha
cd ..
node "playwright/utils/doclint/generateDotnetApi.js" "src/Playwright"
dotnet run --project ./src/tools/Playwright.Tooling/Playwright.Tooling.csproj -- download-drivers --basepath .