Project Edit Command

[JeffreyHuynh1]

Overview

• Provide a way for users to edit project flags in the CLI after a project has been created.
• Allow projects to be associated to multiple teams through the CLI

Acceptance criteria

• Users can modify project flags from the CLI after a project is created.
• Allow associating multiple teams to a project (ANE-1096)

Testing plan

• Added unit tests

• Project Locator Manual Testing

example .fossa.yml:

project:
  locator: custom+1/example
  name: example-title
  teams: 
    - example-team-1
    - example-team-2
  policy: example-policy
  link: fossa.com
  url: github.com/fossas/fossa-cli
  jiraProjectKey: example-jira-key
  labels:
    - example-label-1
    - example-label-2

• fossa project edit --project-locator custom+1/example --title example-title --project-url github.com/fossas/fossa-cli --jira-project-key example-jira-key --link fossa.com --team example-team-1 --team example-team-2 --policy example-policy --project-label example-label-1 --project-label example-label-2

• Project ID Manual Testing
  example .fossa.yml:

project:
  id: example
  name: example-title
  teams: 
    - example-team-1
    - example-team-2
  policy: example-policy
  link: fossa.com
  url: github.com/fossas/fossa-cli
  jiraProjectKey: example-jira-key
  labels:
    - example-label-1
    - example-label-2

• fossa project edit --project-id example --title example-title --project-url github.com/fossas/fossa-cli --jira-project-key example-jira-key --link fossa.com --team example-team-1 --team example-team-2 --policy example-policy --project-label example-label-1 --project-label example-label-2

Risks

Metrics

References

• ANE-863
• ANE-1096

Checklist

• I added tests for this PR's change (or explained in the PR description why tests don't make sense).
• If this PR introduced a user-visible change, I added documentation into docs/.
• If this PR added docs, I added links as appropriate to the user manual's ToC in docs/README.ms and gave consideration to how discoverable or not my documentation is.
• If this change is externally visible, I updated Changelog.md. If this PR did not mark a release, I added my changes into an # Unreleased section at the top.
• If I made changes to .fossa.yml or fossa-deps.{json.yml}, I updated docs/references/files/*.schema.json AND I have updated example files used by fossa init command. You may also need to update these if you have added/removed new dependency type (e.g. pip) or analysis target type (e.g. poetry).
• If I made changes to a subcommand's options, I updated docs/references/subcommands/<subcommand>.md.

[spatten]

Looking good!

The one change I think is necessary is to give some sort of explanation if the org does not suport projects. Other than that, only minor comments

[csasarak]

Some questions:

1. What happens if the project.locator contains a different project id than the value of the project.id I supply?
2. Is it ever necessary to supply both?
3. Can I supply just the project.locator and have the CLI extract the ID portion for operations that need just the project ID?

If the answer to (3) is yes, I think we should discuss with the team describing the project.id as deprecated. We'll still need to support it for the foreseeable future, but the UX of "Copy this string from this place in the UI" Is much better than "Copy a specific substring from this place in the UI, good luck hope you get it right!" IMO.

[JeffreyHuynh1]

1. project.locator only applies for commands project and release-group so if project.id is supplied, it just disregards the value from project.id.
2. Not necessary to supply both as they're used for different commands.
   project.locator -> fossa project & fossa release-group
project.id -> fossa analyze uses the project.id to target specific project revisions
3. There are complications with extracting the id from the project.locator. When running fossa analyze on a new project, users are able to set a custom project.id. Removing project.id means that users lose this functionality, though I am not sure as to how often this feature is used.

[csasarak]

1. Why is it necessary to use a project locator for edit? Based on the description it sounds like a project.id would suffice since a user's API key implies an organization. I'm mainly trying to figure out if we absolutely need these both. They're two values that are very similar so I think it would be easy for a user to use the wrong one.
2. The outcome of discussion on (1) aside, I think that this should be spelled out where the values are defined.
3. It sounds like what you're saying is that extracting it from a project locator is possible, but it would not be backwards compatible. Is that correct? I think you're right regardless though. Plus, it's a crummy UX to force someone to put their org ID before their project name.

Am I mistaken for thinking that the only difference between the locator and id is that one has the org specifier?

[JeffreyHuynh1]

In most cases, the only difference between locator and id is the org specifier.

Given the case that we have:
project.id -> example
orgId -> 1

Usually we get:

project.locator -> custom+1/example

^ But it isn't always the case that project locators are structured like this (confirmed with core)

In this case we can build up the project locator with just project.id and we're able to edit this project accordingly.

However, there are some instances where we normalize the project locator. Sometimes we can have:
project.locator -> git+git/example (or something like this)

In this case there would be no way for us to edit this specific project with just project.id from the cli.

[JeffreyHuynh1]

Projects uploaded through the CLI are structured:

custom+23964/test-package$<version>

reference: https://docs.google.com/document/d/1IZ7TAfsgQekfeq-2wJVtZplp4CquPCzrq4uZlB3OBDY/edit#heading=h.25qf6k4027ah

So if we only want to limit editing projects to only projects uploaded through the CLI, then we can get rid of project.locator and just use project.id.

Thoughts?

[csasarak]

We had a discussion out-of-band and these are the notes:
Notes:

• Discussed how you could have a scenario where project info is set by analyze but that same block is unusable without adding a project-locator key for project edit.
  • In the current PR project edit and release-group... require project.locator but fossa analyze uses project.id
    • Unreasonable to expect a user to know what the project.locator will be for a yet-to-exist project, so we need to keep project.id
    • To properly update projects in core we need to send a full locator
      • Analyze gets around this by simply assuming that the locator is something like custom+XXXX/<project.id>
      • Solution(s):
        • When project edit sees only project.id , do the same thing as analyze to generate a locator.
        • Also: either forbid both project.id and project.locator from being set OR prefer project.locator to project.id.
        • For consistency, analyze needs to be set up to pass project.locator through I think. No matter the reason, all commands should select the same project given the same configuration.
• Because organizations can require a --policy on project creation we can't begin deprecating the fossa analyze project flags until we have a fossa project create command.
• From after our talk: I think that project edit should also accept policy-id if it doesn't. See the analyze flags.

[JeffreyHuynh1]

There were a lot of implementation changes due to the push back from Core. The changes made don't rely on the api/cli/project endpoint I initially created in Core. Instead, we are using existing endpoints to achieve editing project metadata.

[spatten]

I have two big questions.

First, is the change from team to teams in .fossa.yml a breaking change.

Second, should you be able to remove teams from a project using this command. Right now you can only add teams.

A few small nits as well, but let's focus on those right now

[spatten]

Can we make the teams addition idempotent by changing this from add to replace?

[JeffreyHuynh1]

Just tested this and replace actually replaces all the projects for a given team. This means that if used replace, the only the project that we are using through fossa project edit will be present in that team. It overwrites all the existing team projects.

I think the functionality that we're looking for is the inverse of what was previously described. We want to replace all the teams that are associated with a project with the provided list of teams . Unfortunately, this isn't a functionality that is supported through the existing Core endpoints.

I think the best thing to do here is the provide a flag through fossa project edit such as --remove-from-teams or --team-action (Add, Remove), this will allow removing the project from all the listed teams provided through the command. That way we have some way remove projects from teams. We would just need to add remove as a team action.

I've updated the edit.md to let users know that currently fossa project edit only allows adding projects to teams.

Going to create a ticket to add this flag!

[spatten]

Looks good! Thanks for looking into the team/teams thing, and it's too bad that we can't update the teams idempotently.

I think you'll still need to checkin with Chris to make sure you've addressed the changes that they requested.

Chris initially took over the pr review when Scott OOO. I've talked to Chris and we decided that we would leave the final review to Scott as he was assigned initially.