Skip to content

Latest commit

 

History

History
30 lines (22 loc) · 4.74 KB

CONTRIBUTING.md

File metadata and controls

30 lines (22 loc) · 4.74 KB

Contribute Code

You are welcome to contribute to Fluence CLI!

Things you need to know:

  1. You need to agree to the Contributor License Agreement (CLA). This is a common practice in all major Open Source projects. At the current moment, we are unable to accept contributions made on behalf of a company. Only individual contributions will be accepted.

  2. Not all proposed contributions can be accepted. Some features may, e.g., just fit a third-party add-on better. The contribution must fit the overall direction of Fluence and really improve it. The more effort you invest, the better you should clarify in advance whether the contribution fits: the best way would be to just open an issue to discuss the contribution you plan to make.

Contributor License Agreement

When you contribute, you have to be aware that your contribution is covered by GNU Affero General Public License version 3, but might relicensed under few other software licenses mentioned in the Contributor License Agreement. In particular, you need to agree to the Contributor License Agreement. If you agree to its content, you simply have to click on the link posted by the CLA assistant as a comment to the pull request. Click it to check the CLA, then accept it on the following screen if you agree to it. The CLA assistant will save this decision for upcoming contributions and will notify you if there is any change to the CLA in the meantime.

Guidelines for contributors

  • CLI repo consists of a yarn monorepo (that uses turborepo for caching) which contains everything in the ./packages dir + a separate yarn package for CLI itself is needed in the ./packages/cli/package dir (because oclif framework that doesn't work as part of the monorepo). To install yarn you need Node.js 22.10.0 installed and then run corepack enable. Then you run yarn to install all the dependencies for the monorepo and yarn build to build everything.
  • To run tests locally you need to do the following:
    1. Install and run Docker
    2. run e.g. for linux: DEBUG=fcli:*,deal-ts-clients:* yarn test-linux-x64 which will build cli, package it, prepare the tests and run them. For fish shell: env DEBUG="fcli:*,deal-ts-clients:*" yarn test-linux-x64. DEBUG env variable is needed to see debug logs of Fluence CLI and deal-ts-clients lib (you can also inspect js-client logs like by adding fluence:*, libp2p also uses a similar system, check out their docs).
  • PR title must use Conventional Commits (optionally end your commit message with: [fixes DXJ-000 DXJ-001]. Where DXJ-000 and DXJ-001 are ids of the Linear issues that you were working on)
  • To use Fluence CLI in the development mode, run: ./packages/cli/package/bin/dev.js (types are not checked in development mode because it's faster and more convenient to work with. Use typechecking provided by your IDE during development)
  • To use Fluence CLI in the production mode, run yarn build first, then run: ./packages/cli/package/bin/run.js. If you want to make sure you are running the actual package the users will use, do yarn pack-* command for your platform and architecture (this is used for tests as well)
  • Don't name arguments or flags with names that contain underscore symbols because autogenerated links in markdown will not work
  • Don't export anything from command files except for the command itself. If you need to share code between commands - create a separate file
  • Avoid using this in commands except for inside initCli function. This style is easier to understand and there will be less stuff to refactor if instead of using methods on command object you simply use separate functions which can later be moved outside into a separate module for reuse in other commands
  • Use commandObj.error (or throw new CLIError) for human readable errors. They will be reported to analytics as events. Use throw new Error (or assert) for unexpected errors. They will be reported to analytics as crashes.
  • Don't use colors inside commands descriptions. They can't be rendered to markdown and they will not be rendered to users of the packaged Fluence CLI anyway, when they run --help
  • for your convenience a dir .f is added to gitignore so you can generate projects in this dir for testing and development purposes
  • To install packages from fluence npm registry that are published in CI for testing purposes - add npmRegistryServer: https://npm.fluence.dev to .yarnrc.yml. Don't forget removing that before merging your changes into the main branch. You would also need to be logged into npm account that is allowed to access fluence npm registry