DRAFT: A Beginner’s Guide for Contributing to DEM V2

Being part of an open source project means more than just writing code — there are many ways that you can contribute.

Since all the source code for the DEM V2 is open, it's possible to get deeply involved, both in tracking down issues and making significant product changes.

What Contributions Will We Accept

In short, we’ll entertain anything that makes the DEM V2 product better in terms of stability, quality, and capability. This may take the shape of:

  1. Report issue or open the proposal
  2. Bug fixes
  3. Feature implementations
  4. Tests
  5. Documentation
  6. Styles
  7. Translation
  8. DevOps
  9. Create short explainer videos and technical blogs
  10. Invite others to participate

Before you even start writing code, unless its a small bug fix, it is best to subscribe to mailing list and discuss your changes.

Community

The DEM V2 open source community includes developers from around the SEE region. For the latest information and discussions on the topics you’re interested in, join our official communication channels.

Although a lot of discussion happens on the public mailing lists, the community also engages in interactive discussion on Microsoft Teams.

Fixing a Bug

Head back to the Issues liste and look for an issue to fix. Any issue that is not already assigned is up for grabs. I suggest that you leave a comment to say that you have picked this issue up so that you don't end up with more than one person fixing the same thing.

  • Clone the DEM V2 code from GitHub main branch or pull to make sure you have the latest.
  • Create a new branch to host your changes
  • Open the solution and navigate to the code source
  • Implement your fix and retest the repro.
  • Implement test

You’re now ready to create a Pull Request. From within your IDE or Git tool of choice, create a Pull Request against the DEM V2 remote on GitHub. This process should take you to the GitHub Pull Request page and populate with the DEM V2 Pull Request template. We ask that you fill out everything you can, and omit anything that doesn’t apply.

Description What is the current behavior and what is the expected behavior.

Bugs List any and all links that this applies to

API Changes If the surface area of any class changed when making this fix, note the changes here. These may indicate breaking or behavioral changes for other users and their legacy applications.

Checklist Indicate if you have included tests. If no tests are required or the issue is too difficult to test with a UITest, note that.

If at all possible, the test should be automated. If the test cannot be automated, then it should include manual testing instructions on screen.

Please check the "Allow edits from maintainers" checkbox on your pull request. This allows us to quickly make minor fixes and resolve conflicts for you.

And that’s it. Submit the Pull Request and we’ll review it. If there are questions or concerns, the team will submit comments and make requests on code. This review process may feel clinical, so don’t take it personally.

Developer Review and Checks

Now it goes to developer discussion. DEM team members will review and thumbs up or down the PR. All pull requests need to be reviewed and tested by at least one member of the DEM V2 Product team. We do our best to review pull requests in a timely manner, but please be patient! One reviewer will be assigned and will start the review process as soon as possible. If there are any changes requested, the contributor should make them at their earliest convenience or let the reviewers know that they are unable to make further contributions. If the pull request requires only minor changes, then someone else may pick it up and finish it. We will do our best to make sure that all credit is retained for contributors.

Once a pull request has one approval, it will receive an "approved" label. As long as no UI or unit tests are failing, this pull request can be merged at this time.

Merge

Commits will be merged up from stable to prerelease to master branches on a regular basis (typically every Monday and whenever a new release is tagged).

I don’t see any consistency in times when they get merged, but eventually it gets merged into the main branch, then will be tied in with an official release that will eventually end up on Nuget and available for all DEM V2 developers.

  • The current stable branch corresponds to the latest stable version available on NuGet.org. This branch will now only accept regressions or fixes that meet a very high bar and low risk.
  • The current prerelease branch corresponds to the latest prerelease version available on NuGet.org. This branch will only accept bug fixes without API changes or breaking changes, with the exception of any API that is under an experimental flag.
  • Master corresponds to a version that is not yet tagged. This is also the "nightly" branch. This is where anything that doesn't fit into the stable or prerelease branches should be targeted.

Adding Features

Before you start working on a feature, check out the public TFS backlog. Make sure you're working on something in the Ready For Implementation category!

Process is the same as for bug fix

  • Clone the DEM V2 code from GitHub main branch or pull to make sure you have the latest.
  • Create a new branch to host your changes
  • Open the solution and navigate to the code source
  • Implement your favorite feature and retest the repro.
  • Implement test

And that’s it. Submit the Pull Request and we’ll review it.

Test and Wiki

As mentioned, we welcome contributions in these areas as well. We have a several projects for UITests. We have fairly good coverage, but it could always be better. It’s important to test the right things, so if you have any questions please ask.

Documetation

Our team continues to do amazing work on our developer guides and the API documentation. If you spot any inaccuracies or have suggestions, please contribute.

Transaltion

Improve our translations.

Styles and Themes

Improve our visual styles and themes.