"Guidelines for Naming Projects, Tools, or Organizations" section in the readme about openapi-style-guide HOT 25 OPEN

@darrelmiller, thank you for this message. Here some more questions we have with the @OpenAPITools/people.

@jmini Thanks for your feedback on this issue. I'm not sure I agree that the guidance provided is hard to implement. It is true there may be edge cases, but in general, ask the question, is the name of my tooling likely to be misconstrued by someone as an official reference implementation by the OpenAPI Initiative.

We can always ask that simple question but who's going to decide the "correct" answer. Let's start with the question "Do you think X is affiliated with OpenAPI Initiative?" where X is OpenAPITools.org in this case and depending on who you ask the question, you may get different answers: Yes, No, maybe, or other possible answers.

We think the important point is who's going to make the call to decide whether a particular name will cause potential confusion with OpenAPI Initiative. Is that done by a single person at OpenAPI Initiative? or the OpenAPI Initiative TSC going to vote?

Let's look at https://openapi.tools as an example. Arguably one may consider http://openapi.tools to be affiliated with the OpenAPI Initiative. From OpenAPI Initiative, should https://openapi.tools be renamed to something else to avoid potential confusion?

Disclosure: the OpenAPI Generator core team does not own https://openapi.tools. but we did submit pull requests (merged) to include "OpenAPI Generator" in the list.

If a project is under a personal or company repo, then I don't think anyone is going to be confused about the authority of the project. If the organization is completely empty like https://github.com/OpenAPI
and https://github.com/OpenApiFactory then there is not much to be confused about.

Thanks for elaborating a bit more on this. If "OpenApiFactory" publicly forks AutoRest (a code generator owned by Microsoft) to create https://github.com/OpenAPIFactory/AutoRest, will "OpenAPIFactory" need to be renamed to something else to avoid confusion?

What about https://github.com/regga-ws, which has several repositories and uses OpenAPI Initiative's logo but states clearly it's unofficial?

What if "OpenAPIFactory" leaves a very negative comment in a Github issue about open-source projects in general? Following what you said earlier

However, most folks are going to link directly into the repo and never see that caveat.

Your logic above implies "most" users reading the negative comment will not click on the Github account to uncover the fact that the account does not host any repository and therefore has nothing to do with "OpenAPI Initiative".

In this case, do you agree people cannot clearly tell the negative comment or the "OpenAPIFactory" account itself has nothing to do with "OpenAPI Initiative"?

(this is not to say we agree with the statement "However, most folks are going to link directly into the repo and never see that caveat")

There is fairly strong user demand for reference implementations, but the OAI neither has the charter nor the resources to create those, and to do so would be unfair to community efforts. What I personally do not want, is people assuming that the OAI does have reference implementations because of unclear naming.

We do not want people to be confused either as mentioned in our first email reply to Marsh. Do you mind sharing with us how many people you've spoken with to arrive at the conclusion "most" people are confused about OpenAPITools.org being affiliated with OAI? Would you consider a more objective approach by doing a vote on the Twitter account "OpenApiSpec" with the following question?

Do you think OpenAPITools.org (the parent organization of OpenAPI Generator) is affiliated with OpenAPI Initiatives?
Choice 1: Yes
Choice 2: No
Choice 3: Maybe

Poll length: 10 days

Here are two follow-up questions we've after reading your reply:

1. Does it mean "OpenAPI-Generator" (Github repo name) and "OpenAPI Generator" (product name) need not be renamed, which means these names conform to the updated guidelines?

2. In your opinion, do you think the OpenAPI Generator logo (OpenAPITools/openapi-generator#23 (comment)) also violates the updated guideline and will certainly cause confusion to the community?

from openapi-style-guide.

As someone who works in a team that heavily uses OpenAPI / Swagger Spec and who used Swagger Codegen, only recently learning about the OpenAPI Generator project some time after it was created, I can provide some thoughts for @darrelmiller's questions.

Could someone mistake this project for a reference implementation?

It did not occur to me OpenAPI Generator (or any code generator) could be a reference implementation, specifically due to the complexity of the OpenAPI Spec and the fact many organizations still hand-build official SDKs on GitHub.

Also, if there were such a reference implementation, I would expect it to come from https://github.com/OAI because anyone can create any organization name on GitHub. It is first come, first served, like Twitter handles.

Could someone mistakenly interpret the naming as being an indication that the Swagger-codegen project is no longer a maintained effort and that this project is a replacement

Normally one wouldn't look at project B to determine if project A is no longer maintained. When I learned about OpenAPI Generator, the way I checked the status of Swagger Codegen is to check the Swagger Codegen repo and see if:

1. the README.md has a deprecation notice - there isn't
2. there are recent commits - there are
3. there are recent PR reviews / merges - there are

If there's no deprecation notice and there is recent project activity, then the project looks alive, regardless of what some other project is doing.

What is to stop someone from assuming that Swagger-CodeGen has just been renamed to OpenApi-Generator?

In addition to the fact the Swagger Codegen repo still exists with recent activity and no deprecation notice, the OpenAPI Generator README.md history section covers this and mentions it is a fork, which is a commonly known event in open source software, distinct from a rename.

https://github.com/openapitools/openapi-generator#63---history-of-openapi-generator

Also, if the Swagger Codegen project was actually renamed, I feel OpenAPI Codegen would be the appropriate new name. This is because "Codegen" is the defining part of the current name and would provide a sense of continuity.

Do you believe my concern for these confusions are unfounded?

As someone who did not have any idea what OpenAPI Generator was, read the README.md and did some Internet searches, it was clear that it was a fork and not the same project, and also that the original project is still alive with activity. I can't speak for others, but I was not confused.

I appreciate all the effort that went into, and is still going into, both projects. I am following Swagger Codegen progress and interested in the re-architecture on the 3.0.0 branch.

from openapi-style-guide.

Disclaimer: I was a contributor to swagger-codegen for almost a year before becoming a Java Technical Committee member and then becoming a Core Member. Then, the fork happened and I became a core member of openapi-generator. This reply is MY own opinion and I'm NOT talking for the rest of the team or any member of its community.

First of all, let's look at this "problematic" in another angle. The OAI's goal as described here is to "create, evolve and promote" the OpenAPI Specification. You guys should be VERY happy each time a new project implementing your specification pops on the Internet. Your goal is that when someone search for "OpenAPI " on Google, he found a tons of tools and utilities to do whatever he want with its API. He want to see that the specification is alive. You don't want the user to found "RAML" or "API Blueprint". These are the real enemies.

You should not care about how people hear about "OpenAPI ". Did they find with OpenApiTools ? Did they find it with Swagger? Swagger Hub? Nobody cares. The end goal is the same for us all: Have people using OpenAPI with the tools of their choice.

I thinks it's pretty normal for a tools using a specification to have the name of the specification in its name. Imagine if the MP3 was forbidden in project name. How do you call a WavToMP3 converter? (That may not be a perfect example, but I'm pretty sure you understand what I meant)

Again, we, as much as you, want people to find tools when they are searching for tools to work with OpenAPI. If it's clearly said on all our important pages that we are not affiliated with OAI, then I don't see the problem at all. It's a win-win situation where we provide tooling for your specification and more and more people start using your specification all over the world.

As for the logo, I'm no artist but I can say that beside looking a bit similar, it is clearly not a "copy paste".

As for this:

What I am asking is for the project owners to review the naming decisions they have made and ask themselves the question, could this cause confusion in the community.

In most open source project, there are no "project owners". The project is run by the community and that was one of the main reason core members moved from swagger-codegen who was run by a company in the background (plus super bad decision related to breaking changes). We are 100% transparent and public and most decisions are made as a team. The name decision was made via multiple discussion by many many people.

I hope you and other OAI will answer the recurring question asked by our team members in this thread. They are simple and will help a lot to understand the problem. Again, I think there is not problem at all and that our project should work with you guys because we are on the same boat.

Have a good day!

from openapi-style-guide.

I wasn't part of the naming or logo discussion, but the logo discussion and progression is online in the link posted by @jmini above. The logo was originally horizontal but there was a request to make it more squarish and suitable for an icon, which is a common and generic goal. If a vector needs to be chosen, "up and to the right" is often used to indicate progress, and better than other options (left side can indicate going backwards, while downward indicates negative progress). So at least from a vector and positioning perspective, the similarity appears to be coincidental due to the effort to support a square icon vs. being similar to OAI logo. Others that were part of the discussion may be able to comment more.

Here are the two posts that cover this from May 14 and 15.

OpenAPITools/openapi-generator#23 (comment)

from openapi-style-guide.

By way of introduction, I'm a member of the OAI technical, marketing and business governance groups on behalf of RepreZen. Like other OAI members, I'd like to see a constructive resolution to the issues raised here. We recently integrated OpenAPI Generator into RepreZen API Studio, alongside Swagger Codegen and other supported generators, so I guess that's another reason for my interest.

This issue has been in a "cooling off" period, and I'm not anxious to restart conversation here until the OAI Marketing and Business Governance Board have had a chance to review the recent changes to the guidelines, the Linux Foundation guidelines, and the concerns raised by the OpenAPITools team.

But I have had a number of good conversations with William and with various OAI members, and would like to say just a couple of things for the record, hopefully none of which will be controversial:

• There is no question that the OpenAPITools contributors have added a great deal of value to the OpenAPI ecosystem. No other API description language comes close to OpenAPI in its support for popular programming languages and frameworks, both client and server. This is true in large part because of the work that this team has done over the past several years in Swagger-Codegen, and now in OpenAPI-Generator. No one in the OAI is trying to exclude the OpenAPITools group, or single them out for extra scrutiny.
• What we're discussing here is a new community guideline, and an experiment in self-assessment and self-enforcement. We are going to look at this carefully to make sure it's realistic, fair, aligned with Linux Foundation policies, and informed by best practices from other open source ecosystems. Wherever this lands, the guidelines will apply to everyone. If we're asking OpenAPITools to abide by these guidelines, we will also, in due course, ask other project owners to do the same, starting with the OAI members.

The discussion here seemed to have hit a wall, harder and faster than we anticipated. Maybe the circumstances leading up to the issue made it difficult.

We'll get back to the specific questions and concerns soon enough. In the meantime, I didn't want to leave this unresolved without stating the above points explicitly. I hope it helps.

from openapi-style-guide.

There is no question that the OpenAPITools contributors have added a great deal of value to the OpenAPI ecosystem. No other API description language comes close to OpenAPI in its support for popular programming languages and frameworks, both client and server. This is true in large part because of the work that this team has done over the past several years in Swagger-Codegen, and now in OpenAPI-Generator. No one in the OAI is trying to exclude the OpenAPITools group, or single them out for extra scrutiny.

We appreciate the recognition of our voluntary contributions to the OpenAPI community.

What we're discussing here is a new community guideline, and an experiment in self-assessment and self-enforcement. We are going to look at this carefully to make sure it's realistic, fair, aligned with Linux Foundation policies, and informed by best practices from other open source ecosystems. Wherever this lands, the guidelines will apply to everyone. If we're asking OpenAPITools to abide by these guidelines, we will also, in due course, ask other project owners to do the same, starting with the OAI members.

Thanks for listening to our feedbacks and ensuring the same guidelines apply to everyone fairly.

The discussion here seemed to have hit a wall, harder and faster than we anticipated. Maybe the circumstances leading up to the issue made it difficult.

We'd no intention to make the conversation difficult. We definitely want to help make the guideline better for everyone in the OpenAPI community with our feedbacks and questions.

Thanks and regards,
OpenAPI Generator Core Team

from openapi-style-guide.

@jimschubert Ok let me clarify something that I have confused because I wear too many hats in this effort. This isn't a TSC issue at all. The TSC only deals with the technical aspects of the specification. This is an OAI issue. I also am a member of the OAI marketing group and a representative on the OAI governing board. So, when I said the TSC have concerns, I misspoke. The TSC have not discussed this issue officially, and it is not their responsibility. There are members of the OAI marketing group that have concerns. My statement about there not being consensus on the issue is accurate.

from openapi-style-guide.

What we are trying to do is create a level playing field for the community. Having one community project benefit more than others from the marketing efforts of the OAI because they appear to be an "official" implementation is what we are trying to discourage.

For me, the naming has no effect on the "playing field". Here are some thoughts as a maintainer of both Swagger Codegen and OpenAPI Generator SDKs as well as an evaluator of APIMATIC, AutoRest, and go-swagger. The name for a project, especially an OSS project, can be anything so it did not enter into my considerations which included:

• capability and maturity of the tool
• availability of support for the tool

Regarding support for the tool there are two types of OSS projects:

• Community-backed - often best-efforts, non-funded
• Commercially-backed - funded with dedicated resources

From this perspective, a tool with a brand name like Swagger that indicates it is commercially backed by a company can get more adoption (see React vs. Vue). A tool like Swagger Codegen is known to have commercial support and that is a worthwhile consideration when comparing tools.

So if naming is not important for selection, what is important?

I will now post my understanding of the Swagger Codegen situation which I've only read about online because I think it's germane to the level playing field question, primarily if the name doesn't matter, what does?

I had previously created issues for Swagger Codegen and only when I got around to to submitting my first PR did I realize OpenAPI Generator had been created. Swagger Codegen still has active issues, more Stack Overflow questions, etc., so why consider OpenAPI Generator?

1. The first is that community had moved from the README.md file. To adjust to this, Swagger Codegen should recreate a Core Team (the list is currently empty) or remove the Core Team section, and get more template generators on their list.
2. It appears problematic to contribute to Swagger Codegen at the moment, which also appears to be the reason some community members left. As a user of Swagger Codegen, I'd want to submit PRs for it, but it seems like version 2.x is essentially deprecated in favor of 3.x, which isn't ready yet. Version 3.x, the first version to support OAS 3.0, will be different and require rewriting of the templates (few languages supported, tests commented out, etc.). So if I submit a PR for 2.x for a SDK I maintain today, it won't get fixed on 3.x and my work will essentially disappear when attempting to upgrade to 3.x, meaning I will need to deal with the problem again. In this scenario, it seems understandable for there to be reluctance to put effort into Swagger Codegen 2.x and wait for Swagger Codegen 3.x.

Right now, it seems reasonable to consider moving to OpenAPI Generator because OAS 3.0 is already supported, and then potentially reconsider Swagger Codegen when 3.x is released with OAS 3.0 support, languages of interest, refactoring, template system upgrade, etc. An example scenario would be if one wants Handlebars support which comes with Swagger Codegen 3.0 but not OpenAPI Generator at the moment.

If this is not the situation, then more explanation may be useful.

This evaluation has nothing to do with the names of the projects and everything to do with the technical choices made by the projects.

from openapi-style-guide.

@jmini This is my interpretation of a darrelmiller's perspective where he writes:

It is also true that we had no idea how to write these guidelines in an effective way. We are devs and PMs, most likely much like yourselves. We are not lawyers.

This indicates recognition that the guidelines are not perfect and that there may be questions. So expecting the guidelines to be perfectly clear may be unrealistic at present.

Also, not being a lawyer myself, I tend to prefer simple to understand guidelines, for example the MIT license vs. ones designed by lawyers like the Apache 2.0 license.

I believe I can safely speak for the TSC in saying that we have absolutely zero interest in being intellectual property police. We have absolutely no interest in doing anything that would discourage community involvement.

This indicates there is no desire to approve or disapprove of community actions. The idea is to let the community look at the guidelines and make their own judgement.

It appears to me that the members of the OpenApiTools org feel that their actions will have no negative impacts on the community and are enthusiastic about defending that position. I have more constructive things that I could be doing than debating this. I'm prepared to leave it at agreeing to disagree.

I interpret this to mean that he's "ok" if the OpenApiTools team: (a) looks at the guidelines, (b) feels there is no negative impacts, and (c) stays with name choices. That is up to the team to discuss and decide. To me, this is self-policing and it is important to be able to make and explain your decisions.

Further discussion is just for clarification. I continued to post in an effort to alleviate any remaining concerns that may exist, for example, to discuss why I think there may be no negative impacts to the community.

@darrelmiller Please correct me if any of the above is incorrect.

from openapi-style-guide.

@grokify Your interpretation is consistent with my intent. Just to clarify again, I have made the mistake in previous comments that the OAI TSC somehow has an opinion on this, and that was an incorrect statement. This is an issue for the OAI marketing group and the business governing board which has representatives from all the member companies. That is a number in the 40-50 people range. My opinion only counts for so much.

from openapi-style-guide.

@jmini Thanks for your feedback on this issue. I'm not sure I agree that the guidance provided is hard to implement. It is true there may be edge cases, but in general, ask the question, is the name of my tooling likely to be misconstrued by someone as an official reference implementation by the OpenAPI Initiative.

If a project is under a personal or company repo, then I don't think anyone is going to be confused about the authority of the project. If the organization is completely empty like https://github.com/OpenAPI
and https://github.com/OpenApiFactory then there is not much to be confused about.

However, from the list of repos above, the only one that does not clarify that the project belongs to a secondary identity, is openapitools/openapi-generator. I do appreciate the fact that on the organization page there is a note that clarifies that OpenApiTools is not affiliated with the OpenAPI Initiative. However, most folks are going to link directly into the repo and never see that caveat.

There is fairly strong user demand for reference implementations, but the OAI neither has the charter nor the resources to create those, and to do so would be unfair to community efforts. What I personally do not want, is people assuming that the OAI does have reference implementations because of unclear naming.

from openapi-style-guide.

Thanks for the discussion. Branding is an interesting exercise, especially when it relates to open source.

Organization Name and Project Names

If a project is under a personal or company repo, then I don't think anyone is going to be confused about the authority of the project. If the organization is completely empty like https://github.com/OpenAPI
and https://github.com/OpenApiFactory then there is not much to be confused about.

However, from the list of repos above, the only one that does not clarify that the project belongs to a secondary identity, is openapitools/openapi-generator. I do appreciate the fact that on the organization page there is a note that clarifies that OpenApiTools is not affiliated with the OpenAPI Initiative. However, most folks are going to link directly into the repo and never see that caveat.

It seems like most of the concern is about the use of the organization name and the project name together. Here are some additional questions:

Some questions:

1. What are OAI's thoughts on the go-openapi organization at https://github.com/go-openapi? The organization description is currently "OpenAPI Initiative golang toolkit" and they have several projects, unlike the ones mentioned. Should they change their organization name and / or description?
2. It seems the OpenAPI Generator project name by itself is not an issue, but there is concern when associated with the organization name. Also, the organization name seems to be acceptable by itself since it has a disclaimer at the top of the page. On the project page, there is an existing disclaimer that says the following in the README.md. Would putting such a disclaimer in the GitHub repo description at the top of the project repo page alleviate these concerns?

‼️ Both "OpenAPI Tools" (https://OpenAPITools.org - the parent organization of OpenAPI Generator) and "OpenAPI Generator" are not affiliated with OpenAPI Initiative (OAI) ‼️

Organization and Project Logos

In open source, there is a tradition of modifying logos for related projects. This gives a sense of community and association. For example, several organizations / projects that have their logos modified on a regular basis include Linux (penguin), Android, Go (gopher) and Python. Given the many GitHub repos that mention "openapi" in the name there is community interest around OpenAPI. Would OAI be supportive of projects making derivative logos like the other efforts mentioned?

from openapi-style-guide.

Regarding the logo, I'd like to add that I based the logo off of a Robot wall art design in my child's room that we bought from Target. I added a barbell because this is commonly understood as an "interface" from UML.

It took me 15 minutes to create the logo.

The only similarities with OAI logo are the colors.

from openapi-style-guide.

So, @jimschubert you are suggesting that other than the colours, the layout of these two logos is co-incidental and there was no intent to create something that was similar?

from openapi-style-guide.

@jmini We would like the person creating the project to make the decision as to whether there may be confusion. I believe I can safely speak for the TSC in saying that we have absolutely zero interest in being intellectual property police. We have absolutely no interest in doing anything that would discourage community involvement.

What I am asking is for the project owners to review the naming decisions they have made and ask themselves the question, could this cause confusion in the community. Could someone mistake this project for a reference implementation? Could someone mistakenly interpret the naming as being an indication that the Swagger-codegen project is no longer a maintained effort and that this project is a replacement. The specification has been renamed from Swagger to OpenAPI and the OAI members have spent a significant amount of marketing effort explaining this transition. What is to stop someone from assuming that Swagger-CodeGen has just been renamed to OpenApi-Generator? It's forked from the same code-base, right? It has many of the same contributors. Do you believe my concern for these confusions are unfounded?

If the openapi-generator project team feel these concerns of mine are unfounded, that's their choice. I've given my opinion. The document we are discussing are guidelines that are intended to encourage constructive community behavior, nothing more.

from openapi-style-guide.

@darrelmiller just looking for clarification on the logo...

• Are you saying that no community project can use common design elements such as 45° orientation, padding between elements, or a UML-like barbell?
• What exactly are the modifications you're suggesting?
• Are you saying that this logo can be confused for the OAI logo?

I feel like you're suggesting that I copied the logo, which I didn't. I will be happy to share the Affinity Designer project file.

I admit that I used certain design elements to allow the community to associate our project as a tool specific to OpenAPI specifications. I fail to understand why OAI considers this a no-no.

from openapi-style-guide.

@jimschubert I would appreciate it if you didn't put words into my mouth. If you re-read what I wrote, I made zero comments about the logo other than asking you to clarify your statement. I certainly made no statement about what OAI considers a no-no.

I am only concerned about the potential for confusion. As someone who has spent the last two years incessantly explaining to people the difference between OpenAPI and Swagger, I am hyper-sensitive to this issue.

@grokify It is great that you have a process of due diligence when working with OSS projects. If only everyone was a diligent as you.

It appears to me that the members of the OpenApiTools org feel that their actions will have no negative impacts on the community and are enthusiastic about defending that position. I have more constructive things that I could be doing than debating this. I'm prepared to leave it at agreeing to disagree.

from openapi-style-guide.

@darrelmiller if you weren't suggesting that a logo which looks similar with the design elements we've discussed in this thread is against the guidelines, then please explicitly state what you're asking me about.

I think the 3 clarification points I've asked for are reasonable questions, and I'll await responses.

from openapi-style-guide.

@jimschubert You already answered my question. I asked " there was no intent to create something that was similar?" and you replied "I used certain design elements to allow the community to associate our project as a tool specific to OpenAPI specifications. "

Regarding your questions, I believe I made my position clear.

from openapi-style-guide.

@darrelmiller I appreciate that you edited your original response. My questions in this thread aren't meant to get under your skin, I'm just asking for clarifications which I don't feel like I've yet fully received.

To explain why I have questions, openapitools/openapi-generator was released on June 1 2018. On June 8 2018, this repository was updated via a597520 to include the following guidelines about the logo:

For example, if you're considering using the barbell element or the segmented circle, you may want to reach out to the OAI proactively to avoid a rebranding exercise later.

Being that I can't reach out "proactively" weeks after I created the logo, I'm asking my questions here and seeking further clarifications on these guidelines.

Also, I have a few additional questions based on a comment removed by your edit. I thought you were on the TSC, is this incorrect? If incorrect, what's your role? And is there an org chart or something which may clarify my confusion?

Thanks

from openapi-style-guide.

@jimschubert Yes I am a member of the TSC (members are shown here). If I am making statements that convey the policy/decisions of the TSC I will try to be very clear about that. This thread has been about expressing my feelings on the situation as a community member.

It is true that the guidelines were created as a reaction to the perceived issue with the naming of the OpenApiTools/OpenAPI-Generator, so the guidance about proactively reaching out obviously isn't helpful for you. The goal was to prevent us from getting into this situation again.

It is also true that we had no idea how to write these guidelines in an effective way. We are devs and PMs, most likely much like yourselves. We are not lawyers. We perceived a problem and we attempted to provide guidelines to prevent that from happening in the future.

We don't want to ask you to change the name of your project, or change your logo, we would rather be working on features that go into OpenAPI 3.1. But sadly as TSC members we also must deal with other issues. We (the TSC) are concerned about the naming. However, there are varying degrees of concern amongst members. There isn't concensus on what, if any, action should be taken.

Our hope was that by reaching out to you, we could explain our concerns and we could resolve the issue. Secondarily we decided to update our guidelines to reduce the chance that this would happen again. Sadly we have descended into analyzing the words of the guidelines.

I have tried to convey the intent of the guidelines rather than answering direct questions about what the guidelines do and do not allow. Much like debating a Code of Conduct, if we have to define precisely what is and isn't allowed, we are going to have a world of pain.

If you have suggestions on how to re-phrase the guidelines in a way that clearly expresses the intent, we are open to suggestions.

from openapi-style-guide.

@JFCote The suggested change to the guidelines currently reads:

Ask yourself, "Might someone think this was an official tool/project/group of the OAI?" If the answer is, "Maybe," then consider adding a modifier.

Nowhere do we say that you can't use OpenAPI in the project name.

What we are trying to do is create a level playing field for the community. Having one community project benefit more than others from the marketing efforts of the OAI because they appear to be an "official" implementation is what we are trying to discourage.

No-one suggested the logo was a copy-paste. I certainly didn't.

Let's not conflate the conversation about why the fork occurred and this particular issue. It's great that many people contributed to the naming conversation and that you are transparent about these things. Can you point me to the GitHub issue where the conversation happened so I can see the thought process?

from openapi-style-guide.

@darrelmiller I can't because that was done when the fork was "private" and in the process of becoming official. By becoming official and public, we had to create an organization and have a project name so these things had to be decided before going public. But I can assure you it was not decided by one person. It was discussed and we were pretty happy with the final name of the org and the project. We had no bad intention and there were no guidelines from OAI at the time to follow.

I hope that answers your question. I'm leaving for 2 weeks on vacation so I won't be able to answer for a while. Have a good day.

from openapi-style-guide.

I am the feeling that this discussion is going everywhere but not about debating the guideline (which was my initial intention).

My personal opinion about this topic is simple:

Having a guideline that tells 'Asking yourself' is not a good guideline.

Examples:

• http://openapi.tools/
• https://github.com/go-openapi
• https://github.com/OpenAPITools/openapi-generator.

Those 3 projects (created before the update of the README discussed in this issue) can ask them-self if they are not going against the guideline by using the term "OpenAPI" or "OpenAPI Initiative". They could come from OAI.

And because the rules are not clear, there is no definitive answer and it creates an infinite debate like this issue.

from openapi-style-guide.

What is to stop someone from assuming that Swagger-CodeGen has just been renamed to OpenApi-Generator?

The existence of a fork of Swagger-Codegen is not a branding question. One of the reasons is because of disagreements with some fundamental choices made by Swagger-Codegen-v3 and with the governance of the project in general. For more information, please refer to the Q&A in the OpenAPI Generator project page.

Even if the OpenAPI-Generator project was called Codegen-for-OpenAPI (as suggested to be better by the guideline section discussed in this issue) or API-Code-Generator, the users still need to ask themselves the exact same questions:

• Was the project just renamed?
• Is Swagger-Codegen still maintained?
• What is better for me?

In other words, someone can still mistakenly assume that Swagger-CodeGen has been renamed to X where X can be Codegen-for-OpenAPI, API-Code-Generator or something else.

What I am asking is for the project owners to review the naming decisions they have made and ask themselves the question, could this cause confusion in the community. Could someone mistake this project for a reference implementation?

As @grokify has pointed out he didn't mistake this project for a reference implementation nor did he get confused by OpenAPI Generator. This is not to say he represents everyone in the API community. Our point is this goes back to the answer we provided last time:

depending on who you ask the question, you may get different answers: Yes, No, maybe, or other possible answers.

We still think it's important to understand the process in OAI to determine if a particular name will cause confusion to the API community. The question "Asking yourself if the name could imply that the project is an official tool/project/group of the OAI" is not going help as the answer can be very subjective.

Could someone mistakenly interpret the naming as being an indication that the Swagger-codegen project is no longer a maintained effort and that this project is a replacement?

Here are some questions we would like to ask for clarifications:

• From what we know Swagger-Codegen is owned by SmartBear but not by the OpenAPI Initiative (OAI). The discussion starts with whether people may confuse OpenAPITools.org being affiliated with OAI and/or "OpenAPI Generator" being misinterpreted as a reference implementation by the OAI. How is Swagger Codegen (a tool not owned by OAI) relevant to the discussion?
• Are other Swagger-related products/projects such as swagger-ui, swagger-js-codegen also covered by the updated guideline, which means openapi-ui is not allowed for example? (swagger-js-codegen is not owned by SmartBear based on our understanding)
• Does the updated guideline also apply to other OpenAPI tools such as AutoRest (a code generator owned by Microsoft)? In other words, AutoOpenAPI may not be allowed as people may confuse it with AutoRest.
• Does "openapi-generator" conform to the updated guideline if it's a fork of AutoRest but not Swagger Codegen?

It's forked from the same code-base, right? It has many of the same contributors. Do you believe my concern for these confusions are unfounded?

That's the nature of open-source software, especially those licensed with Apache license 2.0. In other words, what you observed - same code-base, same contributors - are common to all forks of projects with Apache 2 license and not just OpenAPI Generator. In Swagger Codegen Github page, you will find that the project has been forked more than 3700 times and some forks are hosted on Gitlab (example) too.

Is it correct to say that one can use https://github.com/openapitools/openapi-generator if it's written from scratch without violating the updated guidelines as the code-base is no longer the same and "many" of the contributors are not the same?

We also think this conversation got sidetracked a little bit to Swagger Codegen in particular. Back to the original concern Marsh shared with OpenAPI Generator core team via email quoted below (which does not mention "Swagger Codegen" at all in the whole email):

To that end, we are concerned that the new organization you've created, OpenAPI Tools, has chosen a name that might easily be confused for an official project of the OAI.

We would appreciate if you, other TSC or OAI marketing group members can answer the following questions:

• From OpenAPI Initiative, should https://openapi.tools be renamed to something else to avoid potential confusion?

• If "OpenApiFactory" publicly forks AutoRest (a code generator owned by Microsoft) to create https://github.com/OpenAPIFactory/AutoRest, will "OpenAPIFactory" need to be renamed to something else to avoid confusion?

• What about https://github.com/regga-ws, which has several repositories and uses OpenAPI Initiative's logo but states clearly it's unofficial?

• What are OAI's thoughts on the go-openapi organization at https://github.com/go-openapi? The organization description is currently "OpenAPI Initiative golang toolkit" and they have several projects, unlike the ones mentioned. Should they change their organization name and / or description? (these questions are from @grokify)

We believe answers to these questions will help the community to understand more about what conforms or does not conform to the updated guidelines and we would recommend including some of these questions and answers in the guidelines.

From Darrel's reply, we feel that he's frustrated with our answers but just so everyone is on the same page, none of the core team members ever works with Darrel. Assuming OpenAPI Generator core team members are bad guys to start with is not good for this discussion even we present different opinions on this matter. We are just open-source project contributors who voluntarily contribute to open-source projects such as Swagger Codegen, Swagger Parser, OpenAPI Generator and more.

Thanks and regards,
OpenAPI Generator Core Team

from openapi-style-guide.