Contributing to NTT

:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:

We welcome contributions to this project of any kind including documentation, plugins, organization, tutorials, bug reports, issues, feature requests, feature implementations, pull requests, answering questions on the mailing list, helping to manage issues, etc.

The first contribution can be scary, but there's no need to worry. Everyone has to start somewhere and we are all nice people who find it great when someone is interested in our project.

Give us a star

Stars help us grow. If you like this project, please give us a star

Reporting Issues

If you believe you have found an issue in ntt, please use the GitHub issue tracker to report the problem. If you're not sure if it's a bug or not, start by asking.

Asking Questions

Our mailing list ntt@groups.io and GitHub Discussions are great places for asking questions and having discussions.

Contributing Code

Use GitHub pull requests to contribute code.

If you are doing this the first time you'll probably have to setup your environment. There are many options, you can use GitHub Codespaces and develop in your browser remotely. Or you install everything on your machine and develop locally:

Installing Go

Install Go using your package manager or a manual installation as described here.
You don't always need the latest version of Go, but you should not use versions older than two years either.

Installing Visual Studio Code

We suggest you install Visual Studio Code.
This is not a hard requirement, you can develop in any editor you like; Vim for example works great, but we find Visual Studio Code is the easiest to start with, especially when you are developing with a Microsoft Windows System.

Installing Git

We use Git for version control and collaborative development. Make sure you have Git installed and configured properly(e.g. user name, email address, GitHub access, ...).

What you should know about Go

This project's main programming language is Go. If you are new to Go, you'll find an introduction here. If you are not sure about the coding style you might find Effective Go and Code Review Comments helpful.

A Pull Request Workflow

Some basic understanding of how to use Git will be of great use. If you know any good tutorials, we'd love to link them here.

For most steps I'll assume you will use a Linux environment, but steps should be similar for MacOS or Windows users. If you have difficulties don't hesitate to ask; we'll help gladly.

Now it's time to get down to business! Please Fork and then clone the repository. The process is described here in good detail.

After you added the upstream remote you can configure git to pull from upstream, to push to your origin repository. This is optional, but I find it quite comfortable:

# Change the remote for from origin to upstream. Pull will use `upstream`:
git config branch.master.remote upstream

# Use `origin` for pushing changes.
git config branch.master.pushRemote origin

Now you're ready to contribute:

0. Create a new branch: git checkout -b my-branch-name. The branch name is not important, for example choose something simple like fix-missing-imports.
1. Make your change and remember to add tests. Write initial tests first; this makes it easier to become familiar the code base.
2. It's a good habit to run all tests locally before creating a pull request: go run ./...
3. Push to your fork and submit a pull request. When you push GitHub will conveniently print the URL for creating a PR on the console. Create a Draft PR, when your contribution is not ready yet. Write a good description so we know what the pull request is about.
4. Pat your self on the back and wait for your pull request to be reviewed and merged. We will review any contribution timely. If you don't get any reaction, please poke us because then we might have overlooked your PR are very sorry about that.

Aftermath and a new Beginning

When your request has been merged and you want to create another pull request, don't forget to:

0. checkout the master branch again.
1. remove the local (git branch -d my-branch-name) and remote feature branch.
2. pull the changes from upstream.
3. synchronize your remote origin repository.

Tips

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

• Write tests.
• Format your code.
• Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, submit them as separate pull requests.
• Write good commit messages.

Repository Organization

ntt                 main binary with sub-commands (list, build, run, lint, ...)
│
├── project         test suite configuration package
├── control         test management and control
│   ├── k3r         runner implementation for k3r
│   └── k3s         runner implementation for k3s
│
├── runtime         runtime system
├── builtins        predefined and builtin functions
├── interpreter     tree walking interpreter for TTCN-3
│
├── ttcn3           language support (semantics and convenience functions)
│   ├── ast         abstract syntax tree and helpers
│   ├── parser      parser (TTCN-3:2018, various extensions, support for Titan, k3 and mtc)
│   ├── scanner     tokenizer
│   ├── token       token types
│   ├── printer     obsolete pretty printer
│   ├── doc         documentation tags package
│   └── v2 	    new TTCN-3 syntax package (WIP)
│
├── internal
│   ├── compdb      compilation database types (compile_commands.json)
│   ├── results     result database types (test_results.json)
│   ├── env         environment file handling (ntt.env)
│   ├── loc         source location package
│   ├── log         logging library
│   ├── proc        subprocess library
│   ├── session     session handling library
│   ├── errors      multi-error implementation
│   ├── fs          file caching and filesystem utilities
│   ├── cache	    path cache package (NTT_CACHE, VPATH)
│   ├── memoize     data caching library
│   ├── lsp         language server
│   ├── pipeconn    net.Conn implementation for os.Stdin/os.Stdout (unsed)
│   └── yaml        YAML support library
│
└── k3              k3 support packages
    └── log         log file parser

Issue and Pull Request Labels

Labels help us track and manage issues and pull requests.

Releasing

Besides source we also provide pre-built binaries. Those binary releases are built using GoReleaser.

Everything is automated, if you want to release ntt, just push a git-tag to this repository. Have a look at existing tags to see how we name things.

When your git-tag went through CI successfully, you'll find a new draft in the releases section. Edit this draft, select your tag and write some nice release notes.

Release notes should be relevant to our users:

• Describe what the new feature is used for and what's problems is solves.
• Add screenshots or screencasts to clarify.
• When breaking compatibility explain why and how the user can fix resulting issues.
• Give shoutouts to our contributors, because we are a community!

Again, have a look at previous releases to get some inspiration what to write.

Dry run If you want to release ntt manually, install goreleaser and try a dry-run first:

$ goreleaser --snapshot --skip-publish --rm-dist

Resources

• How to Contribute to Open Source
• Using Pull Requests
• GitHub Help