-
Notifications
You must be signed in to change notification settings - Fork 173
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
40 changed files
with
1,707 additions
and
365 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| ## `fossa project` | ||
|
|
||
| This `fossa project` subcommand allows users to interact with FOSSA projects. | ||
|
|
||
| It has the following subcommand: | ||
|
|
||
| - [`fossa project edit`](./project/edit.md) | ||
|
|
||
| See the pages linked above for more details. | ||
|
|
||
| ### `fossa project edit` | ||
|
|
||
| Edits a FOSSA project's settings and configurations. | ||
|
|
||
| Example: | ||
|
|
||
| ```bash | ||
| 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 | ||
| ``` | ||
|
|
||
| ### F.A.Q. | ||
|
|
||
| 1. Where can I find my project locator? | ||
|
|
||
| The project Locator defines a unique ID that the FOSSA API will use to reference this project within FOSSA. The project locator can be found in the UI on the project `Settings` page listed as the "Project Locator" underneath the "Project Title" setting. | ||
|
|
||
| <img src="../../assets/project-locator-example.png"> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| ## `fossa project edit` | ||
|
|
||
| `fossa project edit` allows you to edit a FOSSA project's settings and configuration. | ||
|
|
||
| ## Options | ||
|
|
||
| Argument | Required | Description | ||
| -----------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------- | ||
| `--config` / `-c` | No | The to your path to your `.fossa.yml`. | ||
| `--project-locator` | Yes | The project Locator defines a unique ID that the FOSSA API will use to reference this project within FOSSA. The project locator can be found in the UI on the project `Settings` page listed as the "Project Locator" underneath the "Project Title" setting. | ||
| `--project-id` | Yes | The project ID defines an ID that is used to reference a project within your FOSSA organization. The project ID is a specific portion of the project locator and can be found in the UI on the project `Settings` page listed as the "Project Locator" underneath the "Project Title" setting. For example, if the "Project Locator" value of `custom+1/foo` is provided in the FOSSA UI, use `foo`. Project ID defaults to the .git/config file or project's remote "origin" URL (Git), "Repository Root" obtained using 'svn info' (SVN), or the name of the project's directory (No VCS), if project ID wasn't explicityly set during project creation. | ||
| `--title` / `-t` | No | The title of the FOSSA project. | ||
| `--project-url` | No | The url of the project's repository. | ||
| `--jira-project-key` / `-j` | No | The JIRA project key to associate to the FOSSA project. | ||
| `--link` / `-L` | No | A link to attach to the FOSSA project. | ||
| `--team` / `T` | No | The name of the team that will be associated with the FOSSA project. Specify multiple options by providing this argument multiple times. | ||
| `--project-label` | No | The labels associated with the FOSSA project. Assign up to 5 labels for a project. Specify multiple options by providing this argument multiple times. | ||
|
|
||
| > NOTE: The arguments listed as `Required` need to be provided through CLI options OR through your `.fossa.yml` configuration. | ||
| > NOTE: Either project ID OR project locator needs to be set. Project ID takes precedence over project locator. For more details on the differences between project ID and project locator refer to [documentation](../../files/fossa-yml.md#what-is-the-difference-between-project-id-and-project-locator). | ||
| ## .fossa.yml Configuration | ||
|
|
||
| All of the previously mentioned CLI options can be provided through a `.fossa.yml`. Refer to [fossa configuration](../../files/fossa-yml.md) to set up your `.fossa.yml`. | ||
|
|
||
| > NOTE: CLI options take precedence over the configurations in `.fossa.yml`. | ||
| ## `fossa project edit` usage and guidance | ||
|
|
||
| ### Updating a project's labels | ||
|
|
||
| When updating project labels through `fossa project edit`, the transaction is all or nothing. This means that the project labels specified through this command will overwrite the existing labels that are associated with the project. Be sure to include all the labels that you want to be associated with the project, even if some labels are already currently set. | ||
|
|
||
| ### Updating the teams associated with a project | ||
|
|
||
| Currently, `fossa project edit` only supports adding a project to the teams that are specified through the command. There will be support to remove a project from the provided teams in the future. | ||
|
|
||
| Providing teams for `fossa project edit` takes the following precdence: | ||
|
|
||
| 1. CLI options - Adds the project to teams (1 or many) | ||
| 2. `project.teams` in `.fossa.yml` - Adds the project to teams (1 or many) | ||
| 3. `project.team` in `.fossa.yml` - Adds the project to a team | ||
|
|
||
| There is support for `project.team` due to backwards compatability as `project.teams` is a newly added field in `.fossa.yml`. | ||
|
|
||
| ## Example | ||
|
|
||
| ### Project locator example | ||
| Given a project with project locator: `custom+1/example`, the following command: | ||
|
|
||
| - Sets the project's title to `example-title` | ||
| - Set the the project's url to `github.com/fossas/fossa-cli` | ||
| - Sets the project's JIRA key to `example-jira-key` | ||
| - Attaches link: `fossa.com` to the project | ||
| - Adds the project to teams: `example-team-1`, `example-team-2` | ||
| - Attaches policy: `example-policy` to the project | ||
| - Attaches labels: `example-label-1` , `example-label-2` to the project | ||
|
|
||
| ```bash | ||
| 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 --team example-team-2 --policy example-policy --project-label example-label-1 --project-label example-label-2 | ||
| ``` | ||
|
|
||
| Similarly, you can you achieve the same result by running the following command with the given `.fossa.yml` configuration: | ||
|
|
||
| ```bash | ||
| fossa project edit --config /path/to/config | ||
| ``` | ||
|
|
||
| ```yaml | ||
| 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 | ||
| ``` | ||
| ### Project ID example | ||
| Achieve the same result as defined above (for projects created through the CLI) using project ID: | ||
| ```bash | ||
| 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 --team example-team-2 --policy example-policy --project-label example-label-1 --project-label example-label-2 | ||
| ``` | ||
|
|
||
| Similarly, you can you achieve the same result by running the following command with the given `.fossa.yml` configuration: | ||
|
|
||
| ```bash | ||
| fossa project edit --config /path/to/config | ||
| ``` | ||
|
|
||
| ```yaml | ||
| 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 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| module App.Fossa.ApiUtils ( | ||
| retrievePolicyId, | ||
| retrieveTeamIds, | ||
| retrieveLabelIds, | ||
| retrieveTeamIdsWithMaybe, | ||
| ) where | ||
|
|
||
| import Control.Algebra (Has) | ||
| import Control.Effect.Diagnostics (Diagnostics, errHelp, fatalText) | ||
| import Data.Map qualified as Map | ||
| import Data.Maybe (mapMaybe) | ||
| import Data.Text (Text, intercalate) | ||
| import Effect.Logger (pretty, renderIt, vsep) | ||
| import Fossa.API.CoreTypes (Label (..), Labels (..), Policy (..), PolicyType (..), Team (..)) | ||
|
|
||
| retrievePolicyId :: Has Diagnostics sig m => Maybe Text -> PolicyType -> [Policy] -> m (Maybe Int) | ||
| retrievePolicyId maybeTitle targetType policies = case maybeTitle of | ||
| Nothing -> pure Nothing | ||
| Just targetTitle -> do | ||
| let filteredPolicies = filter (\p -> policyTitle p == targetTitle && (policyType p == targetType)) policies | ||
| case filteredPolicies of | ||
| [] -> fatalText $ "Policy `" <> targetTitle <> "` not found" | ||
| [policy] -> pure . Just $ policyId policy | ||
| (_ : _ : _) -> | ||
| errHelp ("Navigate to the FOSSA web UI to rename your policies so that they are unqiue" :: Text) | ||
| . fatalText | ||
| $ "Multiple policies with title `" <> targetTitle <> "` found. Unable to determine which policy to use." | ||
|
|
||
| retrieveTeamIdsWithMaybe :: Has Diagnostics sig m => Maybe [Text] -> [Team] -> m (Maybe [Int]) | ||
| retrieveTeamIdsWithMaybe maybeTeamNames teams = case maybeTeamNames of | ||
| Nothing -> pure Nothing | ||
| Just teamNames -> Just <$> retrieveTeamIds teamNames teams | ||
|
|
||
| retrieveTeamIds :: Has Diagnostics sig m => [Text] -> [Team] -> m [Int] | ||
| retrieveTeamIds teamNames teams = do | ||
| let teamMap = Map.fromList $ map (\team -> (teamName team, teamId team)) teams | ||
| validTeamIds = mapMaybe (`Map.lookup` teamMap) teamNames | ||
|
|
||
| if length teamNames == length validTeamIds | ||
| then pure validTeamIds | ||
| else do | ||
| let missingTeamNames = filter (`Map.notMember` teamMap) teamNames | ||
| fatalText $ "Teams " <> intercalate "," missingTeamNames <> " not found" | ||
|
|
||
| retrieveLabelIds :: Has Diagnostics sig m => [Text] -> Labels -> m ([Int], Maybe [Text]) | ||
| retrieveLabelIds projectLabels (Labels orgLabels) = do | ||
| let orgLabelMap = Map.fromList $ map (\label -> (labelName label, labelId label)) orgLabels | ||
| go orgLabelMap projectLabels [] | ||
| where | ||
| go :: Has Diagnostics sig m => Map.Map Text Int -> [Text] -> [Int] -> m ([Int], Maybe [Text]) | ||
| go _ [] acc = pure (acc, Nothing) | ||
| go labelMap (x : xs) acc = do | ||
| case Map.lookup x labelMap of | ||
| Just labelId' -> go labelMap xs (labelId' : acc) | ||
| Nothing -> do | ||
| (labelIds, maybeWarnings) <- go labelMap xs acc | ||
| let warning = | ||
| renderIt $ | ||
| vsep | ||
| [ "Label `" <> pretty x <> "` does not exist" | ||
| , "Navigate to `Organization Settings` in the FOSSA web UI to create new labels: https://app.fossa.com/account/settings/organization" | ||
| ] | ||
| let updatedWarnings = case maybeWarnings of | ||
| Just warnings -> Just (warning : warnings) | ||
| Nothing -> Just [warning] | ||
| pure (labelIds, updatedWarnings) |
Oops, something went wrong.