Review of projects.md

[CharliePoole]

Hi @nunit/core-team !

This is the first of what will probably be lots of reviews of documentation about the governance of the NUnit project. After some thought, I decided a bottom-up review would work best. That is, the more detailled docs will be reviewed before the higher-level ones. This has the advantage that each review concentrates on one thing and we can gradually build up to the big picture.

For this issue, I'd like to get your comments on projects.md, located in the drafts folder: https://github.com/nunit/governance/blob/master/drafts/projects.md

There are no changes to review, since it's a new document, please comment on the whole thing. Note that I have added special comments headed Reviewers: to point out questionable areas.

Key review points:

• Is the categorization of projects OK?
• Are all the projects where they belong?
• What about the ones I didn't know how to categorize?
• Details of the text

For these reviews, I'd appreciate getting some comment from every core-team member, if only to say that you have read it and see no problems. Thank you!

Charlie

PS: If you want to see the developing big picture, you can look at governance.md in the same folder. It's not ready for review at this point, however.

[rprouse]

The categories and descriptions seem good, the only issues I see is the categorization of some of the projects. In no particular order,

• NUnit Transforms - We only have one user who has shown interest and even he has moved on. I would vote to archive unless a maintainer is found.
• NUnit Xamarin - Chris and I are doing our best to maintain this, Contributed?
• NUnit Distribution - This is just the installer, so ignore or group with the Engine/Console?
• Dotnet Test NUnit - With the change to the .NET Core adapter API, archived.
• NUnit Portable Agent - Same as above

[ChrisMaddock]

I like it! Specifics:

• Would this be a good place to highlight projects that may be 'looking for a maintainer'? I'm thinking samples, project editor...

Reviewers: I'm not sure we should keep all of these projects, but I have listed the ones we have. In particular, I'm inclined to remove two of my own projects, NUnit Summary and NUnit Results. It seems like they just clutter up our project list and don't get much use. I think they can just as well go back to being personal projects. I also wonder about some of the others.

What's NUnit Results?! I agree with NUnit Summary, it just needs a little polish to get it ready for an NUnit 3-supporting release - but we don't seem to have anyone willing to do that. I think it's up to you, @CharliePoole, as to whether you wish to 'remove' it, or add it to the 'archived' list - I don't know the history.

Specific projects:

• Transforms: I guess it could be archived, although it seems low-cost to keep around, and it does work for the latest version of NUnit. I feel like we need a separate status of 'looking for a maintainer', as opposed to everything else in the Archived list, which is pre-3.0 or discontinued. The transform mostly works, just has a bug or two, like everything else. I'm just not sure we have a person to manage the related issues/pull requests.
• Analyzers: This needs further development before being production ready - is this the right place for that?
• Xamarin: I'd like to see it as a secondary project, as I'd like to promote it's use further, and see it as something 'team maintained' - as opposed to the projects on Contributed which seem to have a single maintainer. The line between the two categories is a little sketchy from my point of view however, I'm not overly concerned as to where it ends up.
• Distribution: I don't think needs listing separately.
• dotnettest/agent: I agree with Rob - archive.
• nunit3-tdnet-adapter: shoudl presumably be a contributed project.

[CharliePoole]

We could add a category of projects needing maintainers but I doubt we would get much of an audience here.

Maybe a help wanted page on the website and a notice on the repo. Does GitHub have a place for projects needing maintainers to advertise?

Here I would be more inclined to categorize based on what we want the project to be.

[CharliePoole]

Comments on Chris and Rob's comments...

Nunit Transforms is a special sort of thing, which I forgot about. It's actually set up to aggregate a number of contributed transforms, which are basically small projects in themselves. Right now we have only one: nunit-junit.xslt which was literally contributed to us by the author, who is not availble to do much about maintaining it right now.

In addition to being a sort of aggregate project, NUnit Transforms is a bit different because it is source-based. Users grab the source and can maintain it themselves thereafter. It might be that we don't need to maintain this sort of thing but can just explain in the README that the code is as-is for your use. Alternatively, maybe we should ask the author if he wants to find another maintainer.

For now, I would keep this because I suspect we may be adding some other transforms, but we could review it again at a later time.

[CharliePoole]

Continuing with nunit.xamarin...

I can see it as a secondary project provided we - as a team - want to keep it alive.

@ChrisMaddock the main difference I see with contributed versus core/secondary is that we promise to keep core/secondary things working in the future. There is no such promise with contributed - it's up to the contributor. I think that making this distinction is an important step toward reducing the workload we have to handle in the future.

Correct me if I am wrong... the point of NUnit.Xamarin is that we want to be able to run tests written for android or ios on a device. The gui as well as the tests run on the device. This is needed, among other things, because we don't have any other way to run them. Is that the basically the justification for it?

If that's a correct description, then I agree that it is a secondary project. It would be nice if the only two people working on it were not essential to our core projects as well! However, that's another matter we can deal with at a later point.

Imagine that the two of your were no longer able to maintain it. What would you think we should do then? If the answer is "figure out how to keep maintaining it" then I think it's secondary. If it's "drop it" then maybe not. Ideally, the project category should not have anything to do with whether you guys have time to work on it.

[CharliePoole]

NUnit Distribution - I agree that this is not a separate project for administrative purposes, so I'll drop it from the listing. I've done that for other github repos as well.

In fact, I'm wondering what benefit we are getting from it's being a separate repo. We thought it made sense at one point but I wonder if releasing wouldn't be easier if it were part of the nunit-console repo.

[CharliePoole]

@ChrisMaddock Yes, I forgot the td.net adapter!

[CharliePoole]

@ChrisMaddock Re NUnit Summary and NUnit Results

NUnit Summary displays info about the results of one or more test runs by reading and transforming the xml result files using xsl. I did it as a private project a long time back, as a way to learn about XSL. Since the most important thing I learned was that I didn't like XSL, I didn't do much with it but instead switched to NUnit Results, which displays html reports using C# code.

A while back, somebody popped up who was interested in XSL and wanted to have some improvements in NUnit Summary. I contributed the project to NUnit and we made him the project lead. He made some nice improvements but then things slowed down. I can take a look at it to see what, if anything, I want to do. As I say, I'm not keen on working with XSL.

One possible outcome of this would be to add the transforms to the transforms project and abandon the programmatic part of it entirely. That would eliminate the ability to transform test results after the the test run unless we wanted to make that a feature of the console runner.

In any case, it's a contributed program for the moment.

Listing NUnit Results was an error. It's a private project that I never moved to NUNit.

[CharliePoole]

I updated projects.md based on the comments so far.

For now, I'm continuing to update directly in master but I'll switch to use of a PR for the next document. If you want to just see the changes, you can look at the last commit.

[CharliePoole]

@OsirisTerje @jcansdale Comments please?

[rprouse]

I am on the fence about the Xamarin project. I've worked on several Xamarin.Forms apps and always have a Portable library for the bulk of the app, so I just create a .NET 4.5 test project referencing the PCL to run the tests. I think if I was working on a Xamarin.Android or Xamarin.iOS app that I would be forced to use the NUnit.Xamarin project to run tests as I can't see an alternative. Based on the fact that it is the only way we have to run tests on those platforms, I would lean towards a secondary project. Like you said, I just wish we had more people to help out with it 😄

As for moving the transforms to the transforms project, I think that is probably the best idea. If people want to transform after the test run, they can always use tools like Saxon or other tools to perform the translation. XML transforms should not be our business 😄

I would be in favor of moving distribution back into the console project. I think we made it separate because it is aggregating several projects, but its main purpose is to create an installer for the console/engine, so it should live there. I always find it a pain jumping between the two when creating a release.

[OsirisTerje]

The basic layout of the categories and projects looks good to me.

But I think the Doc project should be regarded as a project in itself. The website project is in, and that is good, but the Doc project is even more important. When talking about that, I feel that it also need more attention than we have been able to give it so far.

I also feel that the Test Adapters should be regarded as one project, not two, and maintained together. If we follow up with the 3-adapter being able to run 2-tests, then it will also revert back to just being one again, which is good.

I like the pre-production project category, because it also opens up for having some experimental projects - as you have added, and using it to try out some ideas without having to make them final to early.

[ChrisMaddock]

One possible outcome of this would be to add the transforms to the transforms project and abandon the programmatic part of it entirely. That would eliminate the ability to transform test results after the the test run unless we wanted to make that a feature of the console runner.

This sounds like a great idea for keeping the recent work done to update these to NUnit 3, whilst not requiring the extra work to bring the rest of the project up to 1.0 level.

• NUnit Distribution - merging it into console sounds good to me

[CharliePoole]

@OsirisTerje I'll add the docs project, although I've started to wonder if our merging the docs together was such a great idea. 😞 However, as it now exists, it is a separate project.

Similarly, for the two VS adapters, they are currently separate projects. We have a lot of decisions to make for them and I felt that it would be pre-judging the Core Team's decision to join them together in this doc.

I think this doc should reflect how things are now - or how they are when we publish it anyway. As we make changes in the project structure, this can change as well.

[CharliePoole]

Created issues for moving distribution back to nunit-console and reviewing the status of nunit-summary.