Skip to content
This repository has been archived by the owner on Feb 26, 2024. It is now read-only.

Update CONTRIBUTING.md file #5162

Merged
merged 3 commits into from
Jun 3, 2022
Merged

Update CONTRIBUTING.md file #5162

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d004236
Update CONTRIBUTING.md
swisstackle Jun 1, 2022
7f600e2
Delete unnecessary sentence
swisstackle Jun 2, 2022
376ef4a
Update CONTRIBUTING.md
swisstackle Jun 2, 2022
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
59 changes: 46 additions & 13 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,37 +33,54 @@ as well as other packages in the monorepo.
### Create a new lerna package

```shell
$ lerna create truffle-mycmd
$ lerna create mycmd
```

### Add the package to `@truffle/core`

```shell
$ lerna add truffle-mycmd --scope=@truffle/core
$ lerna add mycmd --scope=@truffle/core
```

### Create a new command in `@truffle/core`

Create a new file in `packages/core/lib/commands/`, let's call it `mycmd.js`.
1. Create a new directory in `packages/core/lib/commands/`, let's call it `mycmd`.
2. Create 3 javascript files inside the **mycmd** directory with the filenames **run.js**, **meta.js** and **index.js**:
Copy link
Member

@cds-amal cds-amal Jun 2, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A new command needs to be explicitly listed in this index.js as per #5114. Maybe that file should have a comment to that point? @eggplantzzz?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that's true, and in https://github.com/trufflesuite/truffle/blob/develop/packages/core/lib/commands/commands.js

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should figure out a better way to consolidate these so we don't need to maintain this list in two places. Maybe we can just get rid of the index file you mentioned. Buuuuuutt, that is for another day and PR.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@swisstackle I'm delighted you brought attention to this.

Copy link
Contributor Author

@swisstackle swisstackle Jun 2, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cds-amal I believe that that is already mentioned in the file:

Link it from the commands/index.js file

--- packages/core/lib/commands/index.js
+++ packages/core/lib/commands/index.js
@@ -1,4 +1,5 @@
 module.exports = {
+  mycmd: require("./mycmd"),

However there is also the packages/core/lib/commands/commands.js file in the same directory. Do we need to write it in there as well?

Update: @eggplantzzz mentioned it. Nevermind. Ill add it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, commands.js is a file that got recently added when making optimizations to Truffle.

* **run.js** contains the entry function after a user calls your command.
* **meta.js** contains information such as command name and command description.
* **index.js** exports both the run module and the meta module.

#### run.js
```shell
$ cat << EOF > core/lib/commands/mycmd.js
const command = {
$ cat << EOF > core/lib/commands/mycmd/run.js

module.exports = async function (options){
const mycmd = require("mycmd");
// TODO: write the run command here, something like:
// mycmd(options)
};
EOF
```
#### meta.js
```shell
$ cat << EOF > core/lib/commands/mycmd/meta.js
module.exports = {
command: "mycmd",
description: "Run mycmd",
builder: {},
help: {
usage: "truffle mycmd",
options: []
},
run: function(options, done) {
const mycmd = require("truffle-mycmd");
// TODO: write the run command here, something like:
// mycmd(options, done)
}
EOF
```
#### index.js
```shell
$ cat << EOF > core/lib/commands/mycmd/index.js
module.exports = {
run: require("./run"),
meta: require("./meta")
};

module.exports = command;
EOF
```

Expand All @@ -77,6 +94,16 @@ EOF
+ mycmd: require("./mycmd"),
```

### Link it from the commands/commands.js file

```diff
--- packages/core/lib/commands/commands.js
+++ packages/core/lib/commands/commands.js
@@ -1,4 +1,5 @@
module.exports = [
+ "mycmd",
```

From there, you should see it in the help screen:
```shell
$ cd packages/core
Expand All @@ -93,4 +120,10 @@ Commands:

### Write your module/command

The setup is done, you can now write your command and organize your module as you want in: `packages/truffle-mycmd/`. You can have a look at `packages/box/` which is a good starting example to follow.
The setup is done, you can now write your command and organize your module as you want in: `packages/mycmd/`. You can have a look at `packages/box/` which is a good starting example to follow.

### Execute the command
```shell
$ cd packages/core
$ node cli.js mycmd
```