github.com/vugu/vugu@v0.3.5/CONTRIBUTING.md (about)

     1  # Contributing
     2  
     3  Please first discuss via GitHub issue the change you wish to make.
     4  And please follow the code of conduct outlined below during all interactions.
     5  
     6  ## Developing on a Fork
     7  
     8  To work on a copy of Vugu, the easiest way is to use the `replace` module directive as described in https://github.com/golang/go/wiki/Modules#when-should-i-use-the-replace-directive
     9  
    10  This way your forked or local copy of Vugu can correspond to the import path `github.com/vugu/vugu`.  Example:
    11  
    12  ```bash
    13  git checkout https://github.com/vugu/vugu # or, your forked copy
    14  ```
    15  
    16  And now you can reference it from another project:
    17  
    18  some-other-project/go.mod:
    19  ```
    20  module some-other-project
    21  
    22  // point vugu imports at your local copy instead of public download
    23  replace github.com/vugu/vugu => ../vugu
    24  ```
    25  
    26  ## Vugu Project Layout
    27  
    28  Some important subdirectories in the Vugu project are:
    29  * The top level (corresponding to `github.com/vugu/vugu` import path) has common things shared across the other packages.
    30  * `cmd` contains command-line executables, `vugugen` being the most commonly used.  Note that these command-line tools are generally small and just a thin wrapper around functionality from another package.
    31  * `devutil` has utilities specifically created to facility rapid development such as wrappers for each Go+Wasm compilation and an HTTP muxer more suitable for Vugu development than the default one from net/http.
    32  * `domrender` has the client-side code which synchronizes Vugu's virtual DOM tree with the browser's DOM.
    33  * `gen` has code generaiton logic used to convert .vugu files into .go source code.  Most of the implementation of `vugugen` is available here.
    34  * `js` has a wrapper around `syscall/js` which delegates to the default implementation in WebAssembly but in other environments allows compilation and functionality gracefully degrades.  Useful for writing code that needs to compile both in and outside Wasm environments without having to maintain two separate implementations via build tags just to include one reference to e.g. js.Value.
    35  * The following folders are being deprecated and should be used with caution: `simplehttp` is an earlier attempt at development tooling use `devutil` instead.  `tinygo-dev` will be removed, the working parts have moved into `devutil`.
    36  * `wasm-test-suite` contains a test suite using Headless Chrome, see Running Tests below.
    37  
    38  ## Running Tests
    39  
    40  In `wasm-test-suite`, `run-wasm-test-suite-docker.sh` can be used to launch a docker container with Headless Chrome and a small server.  You can then use `go test` in `wasm-test-suite` to execute the various end-to-end tests available.
    41  
    42  This requires Docker to be installed properly and the test suite expects to be able to connect the running docker instance on ports 8846 for web serving/upload and port 9222 to control Headless Chrome.
    43  
    44  ## Vugu Documentation
    45  
    46  Documention for Vugu, other than GoDoc (https://pkg.go.dev/github.com/vugu/vugu), lives on https://vugu.org.  The source for it is at https://github.com/vugu/vugu-site and you can submit PRs to that repository to propose changes.  For small improvements and errata it is fine to just submit a PR.  For more significant changes or if a discussion is required, please create a GitHub issue first
    47  
    48  ## Submitting Pull Requests
    49  
    50  Please make sure that any PRs:
    51  * Only include necessary modifications.  Avoid unnecessary changes such as reformatting code, renaming existing variables and the like unless previously discussed via issue.
    52  * Do not include files not intended for version control - .DS_Store, compiled binaries, debug output, etc.
    53  * Try hard to not break publicly exposed APIs.  The more likely a change is to cause breakage for other issues, the more vital prior discussion is.  Vugu is not yet 1.0 but compatibility is taken seriously nonetheless.
    54  * Introducing new publicly exposed APIs, as mentioned above, require discussion first.  Depending on the feature, it may be okay to introduce some things as a prototype, but in general before something gets merged into master, both you and the Vugu maintainers should be happy with the design.
    55  
    56  ## Code of Conduct
    57  
    58  ### Our Pledge
    59  
    60  In the interest of fostering an open and welcoming environment, we as
    61  contributors and maintainers pledge to making participation in our project and
    62  our community a harassment-free experience for everyone, regardless of age, body
    63  size, disability, ethnicity, gender identity and expression, level of experience,
    64  nationality, personal appearance, race, religion, or sexual identity and
    65  orientation.
    66  
    67  ### Our Standards
    68  
    69  Examples of behavior that contributes to creating a positive environment
    70  include:
    71  
    72  * Using welcoming and inclusive language
    73  * Being respectful of differing viewpoints and experiences
    74  * Gracefully accepting constructive criticism
    75  * Focusing on what is best for the community
    76  * Showing empathy towards other community members
    77  
    78  Examples of unacceptable behavior by participants include:
    79  
    80  * The use of sexualized language or imagery and unwelcome sexual attention or
    81  advances
    82  * Trolling, insulting/derogatory comments, and personal or political attacks
    83  * Public or private harassment
    84  * Publishing others' private information, such as a physical or electronic
    85    address, without explicit permission
    86  * Other conduct which could reasonably be considered inappropriate in a
    87    professional setting
    88  
    89  ### Our Responsibilities
    90  
    91  Project maintainers are responsible for clarifying the standards of acceptable
    92  behavior and are expected to take appropriate and fair corrective action in
    93  response to any instances of unacceptable behavior.
    94  
    95  Project maintainers have the right and responsibility to remove, edit, or
    96  reject comments, commits, code, wiki edits, issues, and other contributions
    97  that are not aligned to this Code of Conduct, or to ban temporarily or
    98  permanently any contributor for other behaviors that they deem inappropriate,
    99  threatening, offensive, or harmful.
   100  
   101  ### Scope
   102  
   103  This Code of Conduct applies both within project spaces and in public spaces
   104  when an individual is representing the project or its community. Examples of
   105  representing a project or community include using an official project e-mail
   106  address, posting via an official social media account, or acting as an appointed
   107  representative at an online or offline event. Representation of a project may be
   108  further defined and clarified by project maintainers.
   109  
   110  ### Enforcement
   111  
   112  Instances of abusive, harassing, or otherwise unacceptable behavior may be
   113  reported by contacting the project team at admin at vugu dot org. All
   114  complaints will be reviewed and investigated and will result in a response that
   115  is deemed necessary and appropriate to the circumstances. The project team is
   116  obligated to maintain confidentiality with regard to the reporter of an incident.
   117  Further details of specific enforcement policies may be posted separately.
   118  
   119  Project maintainers who do not follow or enforce the Code of Conduct in good
   120  faith may face temporary or permanent repercussions as determined by other
   121  members of the project's leadership.
   122  
   123  ### Attribution
   124  
   125  This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
   126  available at [http://contributor-covenant.org/version/1/4][version]
   127  
   128  [homepage]: http://contributor-covenant.org
   129  [version]: http://contributor-covenant.org/version/1/4/