Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 24 additions & 21 deletions docs/collaboration-infrastructure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -314,10 +314,10 @@ In order to consolidate processes and tools around security vulnerabilities mana
7. A [SECURITY.md](https://github.com/finos/software-project-blueprint/blob/main/SECURITY.md) file in the repository root, linking to the [FINOS Security Vulnerabilities Responsible Disclosure Policy](https://community.finos.org/docs/governance/software-projects/cve-responsible-disclosure/)
8. Issue templates for bugs, feature requests and support questions , [defined in the `.github` folder](https://github.com/finos/software-project-blueprint/tree/master/.github/ISSUE_TEMPLATE)

Placeholders are defined using the `{}` brackets.
Placeholders use `{UPPER_SNAKE_CASE}` tokens throughout the blueprint.

#### Creating a new repository
Anyone can use the Project blueprint repository, simply accessing [https://github.com/finos/project-blueprint](https://github.com/finos/project-blueprint) and pressing the `Use this template` button and following instructions.
Anyone can use the Project blueprint repository, simply accessing [https://github.com/finos/software-project-blueprint](https://github.com/finos/software-project-blueprint) and pressing the `Use this template` button and following instructions.

The main `README.md` file contains instructions on how to replace placeholders across all blueprint files.

Expand All @@ -329,30 +329,33 @@ The project blueprint comes with a pre-definite website that is built using Docu

Getting started is quite simple:

1. Make sure that your GitHub repository includes the `docs/` and `website/` folder from the [project-blueprint](https://github.com/finos/project-blueprint)
1. Make sure that your GitHub repository includes the `docs/` and `website/` folder from the [software-project-blueprint](https://github.com/finos/software-project-blueprint)
2. Read our <a href={useBaseUrl('/docs/development-infrastructure/project-documentation')}>getting started guide</a> to understand more about Docusaurus`

#### How to use this blueprint
1. Visit on https://github.com/finos/project-blueprint
2. Click on `Use this template` and follow instructions
3. Copy the `README.template.md` file to your repository, and rename it to `README.md`.
4. Search and replace the following tokens in the newly copied files:

| Token | Replace with |
| ---------------------------- | ----------------------------------------------------------------- |
| `{project name}` | The name of the FINOS Project, ie `Open Developer Platform` |
| `{project slug}` | The name of the GitHub repository the project resides in, ie `software-project-blueprint` |
| `{yyyy}` | The year you started working on the code. |
| `{current year}` | The current year. |
| `{name of copyright owner}` | The copyright owner of the code (typically you or your employer). |
| `{email of copyright owner}` | The email address of the copyright owner of the code (if known). |

5. Open the `NOTICE` file in a text editor and either remove the `{Other notices, as necessary}` token, or [add attributions if required by your code's dependencies](/docs/governance/Software-Projects/license-categories).
6. Open the `README.md` file in a text editor and complete the content as appropriate for your project.
7. Open the `MAINTAINERS.md` file in a text editor and list all maintainers and their contact information.
1. Visit https://github.com/finos/software-project-blueprint
2. Click on `Use this template` and follow GitHub's instructions.
3. In your new repository, copy `README.template.md` to `README.md` (replacing this file).
4. Search and replace the following tokens across the copied files:

| Token | Replace with |
| ----- | ------------ |
| `{PROJECT_NAME}` | The name of the FINOS project, e.g. `Open Developer Platform` |
| `{PROJECT_SLUG}` | The GitHub repository name, e.g. `software-project-blueprint` |
| `{PROJECT_URL}` | The GitHub repository URL, e.g. `https://github.com/finos/software-project-blueprint` |
| `{PROJECT_MAILING_LIST}` | The project mailing list address, if any |
| `{YYYY}` | The year you started working on the code |
| `{CURRENT_YEAR}` | The current year |
| `{NAME_OF_COPYRIGHT_OWNER}` | The copyright owner of the code (typically you or your employer) |
| `{EMAIL_OF_COPYRIGHT_OWNER}` | The email address of the copyright owner of the code (if known) |
| `{OTHER_NOTICES}` | Additional NOTICE attributions required by dependencies, or remove this token |

5. Open the `NOTICE` file and either remove `{OTHER_NOTICES}` or [add attributions if required by your code's dependencies](/docs/governance/Software-Projects/license-categories).
6. Open `README.md` and complete the content as appropriate for your project.
7. Open `MAINTAINERS.md` and add maintainer names, GitHub usernames, and email addresses.
8. Add the [Apache license header to all of your source files](https://www.apache.org/licenses/LICENSE-2.0.html#apply).
9. (optional) Remove the `EASYCLA_CHANGEME.md`, `.node-version`, and `renovate.json` files, if not applicable to your project.
10. (optional) Remove the `docs/` and `website/` folders + the `netlify.toml` file, if you're not interested to have a project documentation website in place.
10. (optional) Remove the `docs/` and `website/` folders + the `netlify.toml` file, if you do not need a project documentation website.
11. Commit and push all of your changes.

### Automated and continuous quality scanning
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ FINOS have rolled out the [Mend (formerly WhiteSource) integration for GitHub.co
There are 2 configuration files to define at repository level, in order to enable the WhiteSource integration with GitHub.com: .whitesource file configures the bot and whitesource.config configures the WhiteSource agent.

#### .whitesource
Specifies whether to use GitHub Issues or not and points to the WhiteSource agent configuration. You can copy this file definition from https://github.com/finos/project-blueprint
Specifies whether to use GitHub Issues or not and points to the WhiteSource agent configuration. You can copy this file definition from https://github.com/finos/software-project-blueprint

```
.whitesource
Expand All @@ -105,7 +105,7 @@ Specifies whether to use GitHub Issues or not and points to the WhiteSource agen
```

#### whitesource.config
Specifies build-time configurations, including language-specific settings, file inclusions/exclusions and more. You can copy the default configuration from [FINOS project blueprint](https://github.com/finos/project-blueprint). More info can be found on the [Unified Agent configuration parameters](https://docs.mend.io/legacy-sca/latest/unified-agent-configuration-parameters) docs page.
Specifies build-time configurations, including language-specific settings, file inclusions/exclusions and more. You can copy the default configuration from [FINOS software project blueprint](https://github.com/finos/software-project-blueprint). More info can be found on the [Unified Agent configuration parameters](https://docs.mend.io/legacy-sca/latest/unified-agent-configuration-parameters) docs page.

### Enable WhiteSource scanning

Expand Down
4 changes: 2 additions & 2 deletions docs/development-infrastructure/project-documentation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,14 @@ In order to add a website to an existing project, see the <a href={useBaseUrl('/

Docusaurus is a static website generator written in React, available open source under the Apache 2.0 license. It is technologically similar to Jekyll, which integrates tightly with GitHub Pages but lacks modern development support and local development tools.

Given the significant adoption of Docusaurus within FINOS projects, it has become our go-to solution for building project documentation websites. If you're just getting started, use the [FINOS project blueprint](https://github.com/finos/project-blueprint) repository template and follow the [blueprint documentation](https://community.finos.org/docs/collaboration-infrastructure/#finos-project-blueprint) to get started which includes a built-in Docusaurus website.
Given the significant adoption of Docusaurus within FINOS projects, it has become our go-to solution for building project documentation websites. If you're just getting started, use the [FINOS software project blueprint](https://github.com/finos/software-project-blueprint) repository template and follow the [blueprint documentation](https://community.finos.org/docs/collaboration-infrastructure/#finos-project-blueprint) to get started which includes a built-in Docusaurus website.

The full Docusaurus documentation can be found on the [Docusaurus website](https://docusaurus.io/).

### Get Started in 5 Minutes

:::info
The following steps refer to Docusaurus 3.x and how it is used in conjunction with the [FINOS project blueprint](https://github.com/finos/project-blueprint).
The following steps refer to Docusaurus 3.x and how it is used in conjunction with the [FINOS software project blueprint](https://github.com/finos/software-project-blueprint).
:::

Ensure NodeJS and NPM are installed:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -56,16 +56,14 @@ A `LICENSE` file must be present at the root of each project, and must contain t
### The NOTICE file
A `NOTICE` file must be present at the root of each project, and must contain the copyright notices of each copyright holder who has contributed to the project. If you are contributing to an existing project, you should add (or update) your copyright notice in the `NOTICE` file. A sample `NOTICE` file (Markdown format) is provided in the [FINOS Software project blueprint](https://github.com/finos/software-project-blueprint). It must also contain any other attributions required by third-party dependencies (see below).

You should use this template for your `NOTICE` file:
You should use this template for your `NOTICE` file (from the [FINOS Software project blueprint](https://github.com/finos/software-project-blueprint/blob/main/NOTICE)). Add a `Copyright` line for each copyright holder who has contributed to the project:
```
[PROJECT_NAME] - FINOS
Copyright [XXXX-XXXX] [Copyright holder 1 - name and email]
Copyright [XXXX-XXXX] [Copyright holder 2 - name and email] ...
Copyright [XXXX-XXXX] [Copyright holder N - name and email]
{PROJECT_NAME} - FINOS
Copyright {YYYY} - {CURRENT_YEAR} {NAME_OF_COPYRIGHT_OWNER} {EMAIL_OF_COPYRIGHT_OWNER}

This product includes software developed at the Fintech Open Source Foundation (https://www.finos.org/).
[Other notices, as necessary]

{OTHER_NOTICES}
```

### The CONTRIBUTING file
Expand All @@ -78,7 +76,7 @@ For [Graduated](/docs/governance/lifecycle-stages/graduated) projects, it's reco

```
SPDX-License-Identifier: Apache-2.0
Copyright [yyyy] FINOS [Project Name] contributors - see NOTICE file
Copyright {YYYY} FINOS {PROJECT_NAME} contributors - see NOTICE file

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand All @@ -97,19 +95,19 @@ If space is at a premium, you are welcome to use an abbreviated version like the

```
SPDX-License-Identifier: Apache-2.0
Copyright [yyyy] FINOS [Project Name] contributors - see NOTICE file
Copyright {YYYY} FINOS {PROJECT_NAME} contributors - see NOTICE file
```

### SPDX information
We encourage project teams to place a [SPDX-format](https://github.com/david-a-wheeler/spdx-tutorial#spdx-files) `LICENSE.spdx` file in the root of each project. SPDX is a standard for describing machine-readable license information about open source projects. For more information on SPDX, please see the [SPDX website](https://spdx.org/). See below for a basic example `LICENSE.spdx` file. For a tutorial on adding SPDX information to a project, [see here](https://github.com/david-a-wheeler/spdx-tutorial/blob/master/README.md).

```
SPDXVersion: SPDX-2.1
SPDXVersion: SPDX-2.0
DataLicense: CC0-1.0
Creator: John Smith (jsmith@acme.com)
PackageName: example-project
PackageOriginator: John Smith (jsmith@acme.com)
PackageHomePage: https://github.com/finos-<program name>/example-project
Creator: {NAME_OF_COPYRIGHT_OWNER}
PackageName: {PROJECT_NAME}
PackageOriginator: {NAME_OF_COPYRIGHT_OWNER}
PackageHomePage: https://github.com/finos/{PROJECT_SLUG}
PackageLicenseDeclared: Apache-2.0
```

Expand Down
Loading