Proposal: Reorganize directories for simplicity and clarity

Main Goals

• Simplify root directory so the repository feels more accessible to first time readers or contributors.
  • There are 4 sample* directories and 2 reproduction* directories that should be more clearly identified as test projects
  • There are several build and test files cluttered in the root directory that could be placed in more specific subdirectories
• Change the convention of “customer-samples” to “samples”. My assumption is that new developers would expect to look at samples as small code projects that use the provided SDK in some meaningful way, so this proposed change would align with that.
• Change the convention of “samples” to “test-applications”. The “samples” in our repository really act as test applications to ensure our automatic instrumentation works as advertised. Renaming to “test-applications” is a little more clear about the intent, but I’m open to other suggestions on the name of this.
• Change the convention of “reproductions” to “regression”. These test applications serve as small regression tests to make sure previous bugs do not reoccur. Renaming to regression might convey that idea more clearly.

Proposed directory structure

Directory: /

Subdirectory name	Purpose
blog	Articles and walkthroughs (i.e. not code) to describe how the .NET Tracer can be used in various scenarios
build	Contains artifacts, docker files, shell scripts, and code needed to run builds and CI
docs	High-level documents
samples	Previously named customer-samples, this contains .NET code that can be easily built against the Datadog.Trace NuGet package to demonstrate how it can be used for custom instrumentation
src	Contains all project files and source files for .NET code, profiler code, and MSI code
test	Contains all test projects (managed and native) and test applications
tools	Miscellaneous .NET projects that are not product code or directly related to generating build artifacts

Directory: /build

Subdirectory name	Purpose
artifacts	createLogPath.sh, Datadog png’s, and integrations.json
docker	Directly moved from the /docker directory
tools	Contains GeneratePackageVersions and PrepareRelease that were previously in the /tools directory

Directory: /blog

Contents unchanged

Directory: /docs

Contents unchanged

Directory: /samples (renamed from /customer-samples)

Contents unchanged

Directory: /src

Subdirectory name	Purpose
WindowsInstaller	Project that generates MSI. Directly moved from the /deploy/Datadog.Trace.ClrProfiler.WindowsInstaller directory
Datadog.Trace.ClrProfiler.Native/lib	CoreCLR headers needed to build CLR Profiler. Directly moved from the /lib directory
Remaining Datadog.Trace.* projects	Unchanged

Directory: /test

Subdirectory name	Purpose
benchmarks	Contains all benchmark projects
Datadog.Trace.*Tests	Unchanged
test-applications	All sample applications intended to test automatic instrumentation will be moved to this directory

Directory: /tools

Subdirectory name	Purpose
Datadog.Core.Tools	Unchanged
StartDistributedTrace	Unchanged
UpdateVendors	Unchanged

Directory: /test/test-applications

Subdirectory name	Purpose
aspnet	Contents will be a combination of the original /samples-aspnet directory and the /samples-iis directory
integrations	Directly moved from the /samples directory
integrations/dependency-libs	Directly moved from the /sample-libs directory
regression	Directly moved from the /reproductions directory
regression/dependency-libs	Directly moved from the /reproduction-dependencies directory

Updates

• Originally the two subfolders aspnet and iis were proposed as subdirectories of /test/Datadog.Trace.ClrProfiler.IntegrationTests/test-applications. Instead, they’ll be combined into the aspnet subdirectory
• Originally the test-applications directory was proposed to be a subdirectory of /test/Datadog.Trace.ClrProfiler.IntegrationTests. Instead, it will be a subdirectory of test
• Updated new directory name to /src/WindowsInstaller based on feedback
• Updated the proposal to reflect the directory move from /lib to /src/Datadog.Trace.ClrProfiler.Native/lib

[zacharycmontoya]

I have a branch with all of the changes at https://github.com/DataDog/dd-trace-dotnet/tree/zach/directory-restructuring . Since this touches a lot of files, it might be easier for reviewers to review one subdirectory tree at a time. If that sounds good, I can begin preparing the 6 PR’s separately:

1. build
2. samples
3. src/Datadog.Trace.ClrProfiler.Native/lib
4. src/Datadog.Trace.ClrProfiler.WindowsInstaller
5. test/benchmarks
6. test/test-applications

[zacharycmontoya]

To your points @lucaspimentel :

• I’m not sure I would move benchmarks inside test, but I don’t feel strongly about it.

I could be swayed either way on this one, as moving it inside test helps remove clutter from the root while at the same time it’s not really a functional test. I wonder if there are other opinions on this particular move.

• Moving test-applications inside Datadog.Trace.ClrProfiler.IntegrationTests seems weird to me, since the latter already contains a project. We don’t place project folders inside other projects folders anywhere else, and it would require excluding child folders when building the parent. Can we move it to test/test-applications instead so it’s a sibling of Datadog.Trace.ClrProfiler.IntegrationTests?

Yes that sounds completely reasonable. The main goal is to move them out of the root. I think @pjanotti and I were going back and forth on where to put the test-applications folder. Placing it at test/test-applications is fine by me ✔️

• I think we can merge the iis and aspnet folders. What sets them apart from other test apps is that they cannot be SDK-style projects and they require a blank Directory.Build.props.

Yes I agree. I’ll make that modification in the proposal at the top.